Gatrix 운영자 매뉴얼

📖 목차 (Table of Contents)

이 매뉴얼은 Gatrix 대시보드를 사용하는 게임 운영자를 위한 종합 가이드입니다.

🏠 시작하기

장 제목 설명
1 소개 Gatrix란 무엇인가? 주요 기능 개요, 다국어 안내
2 대시보드 개요 화면 구성, 환경 선택, 기본 조작법
2-1 ⭐ 환경 관리 환경별 데이터 격리, 공유 정책, 환경 혼동 방지

👤 관리자 설정

장 제목 설명
3 사용자 관리 운영자 계정 생성, 권한 부여, 온/오프보딩
4 클라이언트 버전 관리 앱 버전 관리, 강제 업데이트, 스토어 심사

🎮 게임 서비스 운영

장 제목 설명
5 게임 월드 관리 서버 목록 관리, 월드별 상태 제어
6 ⭐ 점검 관리 서비스/월드/버전별 점검, 화이트리스트
7 공지사항 관리 서비스 공지 작성, Rich Text Editor
8 인게임 팝업 관리 긴급 안내, 팝업 우선순위

🎁 프로모션 & 마케팅

장 제목 설명
9 쿠폰 관리 쿠폰 발행, NORMAL/UNIQUE 유형
10 설문조사 관리 유저 설문, 참여 보상

🏪 상점 & 콘텐츠

장 제목 설명
11 상점 상품 관리 IAP/인게임 상품 관리
12 배너 관리 시퀀스 기반 동적 배너
13 기획 데이터 관리 Excel → JSON 변환, 버전 관리
14 리모트 컨피그 원격 설정, A/B 테스트

🔒 보안 & 모니터링

장 제목 설명
15 감사 로그 관리자 활동 추적, 보안 감사
16 API 토큰 관리 서버 인증, 토큰 보안

🆕 이번 버전 주요 추가 내용

항목 설명
환경 관리 환경별 데이터 격리/공유 정책, 환경 혼동 방지 가이드
점검 체계 서비스 전체/월드별/버전별 점검, 실시간 vs API 조회
화이트리스트 계정 ID, IP 주소 기반 (Device ID 미지원)
다국어 안내 단일 국가 서비스 시 다국어 메시지 불필요 안내
트러블슈팅 각 기능별 문제 해결 케이스 추가
동영상 가이드 직접 재생 가능한 동영상 포함

📂 문서 구조

manual/ko/
├── 00-table-of-contents.md   # 이 파일 (목차)
├── 01-introduction.md         # 소개 + 다국어 안내 + 영상
├── 02-dashboard.md            # 대시보드 개요
├── 02-1-environments.md       # ⭐ 환경 관리 (신규)
├── 03-user-management.md      # 사용자 관리 + 트러블슈팅
├── 04-client-versions.md      # 클라이언트 버전 + 트러블슈팅
├── 05-game-worlds.md          # 게임 월드 관리
├── 06-maintenance.md          # ⭐ 점검 관리 (대폭 보강)
├── 07-service-notices.md      # 공지사항 + 트러블슈팅
├── 08-popup-notices.md        # 인게임 팝업 관리
├── 09-coupons.md              # 쿠폰 관리
├── 10-surveys.md              # 설문조사 관리
├── 11-store-products.md       # 상점 상품 관리
├── 12-banners.md              # 배너 관리
├── 13-planning-data.md        # 기획 데이터 관리
├── 14-remote-config.md        # 리모트 컨피그
├── 15-audit-logs.md           # 감사 로그
├── 16-api-tokens.md           # API 토큰 관리
├── images/                    # 스크린샷 이미지
└── videos/                    # 동영상 가이드

🔍 빠른 검색

상황별 가이드

상황 해당 장
신규 운영자 입사 3장: 사용자 관리
앱 업데이트 배포 4장: 클라이언트 버전 관리
긴급 점검 필요 6장: 점검 관리
이벤트 공지 작성 7장: 공지사항 관리
쿠폰 발급 9장: 쿠폰 관리
보안 감사 수행 15장: 감사 로그
환경 혼동 방지 2-1장: 환경 관리

📋 문서 정보

→ 다음: 제 1장 소개

제 1장: 소개 (Introduction)

Gatrix란 무엇인가요?

Gatrix는 온라인 게임 서비스 운영에 필요한 모든 기능을 통합적으로 관리할 수 있는 게임 서비스 대시보드(Game Service Dashboard)입니다.

Gatrix를 통해 다음과 같은 업무를 수행할 수 있습니다:
- 게임 클라이언트 관리: 앱 버전 등록, 강제 업데이트 설정, 점검 모드 전환
- 게임 월드 관리: 게임 서버 등록 및 상태 관리 (혼잡도, 점검 중 표시 등)
- 플레이어 소통: 공지사항, 인게임 팝업, 설문조사 등을 통한 정보 전달
- 프로모션: 쿠폰 코드 발행, 배너 관리, 이벤트 진행
- 운영 모니터링: 서버 상태 확인, 관리자 활동 로그(Audit Log) 추적
- 실시간 제어: 클라이언트 패치 없이 게임 설정 변경 (Remote Config)

사용 대상

이 매뉴얼은 게임 서비스를 실제 운영하는 게임 서비스 담당자(GM, 운영자, QA, 사업 PM)를 위해 작성되었습니다.

주요 독자:
- 일일 게임 운영을 담당하는 운영자 (GM)
- 이벤트 및 프로모션을 기획하고 실행하는 사업 담당자
- 서버 점검 및 배포를 관리하는 기술 담당자
- 사용자 권한을 관리하는 최고 관리자

참고: 이 매뉴얼은 개발자가 아닌 사용자(운영자) 관점에서 작성되었습니다. SDK 연동 등 기술적인 내용은 포함되어 있지 않습니다.

시스템 요구사항

브라우저 지원

Gatrix 대시보드는 최신 웹 표준을 준수하며, 다음 브라우저에서 최적화되어 있습니다:
- Google Chrome (권장)
- Microsoft Edge
- Mozilla Firefox
- Safari

기타

접속하기

로그인

  1. 브라우저에서 Gatrix 대시보드 주소로 접속합니다.
  2. 이메일(아이디)과 비밀번호를 입력합니다.
  3. 로그인 버튼을 클릭합니다.

로그인 페이지

🎬 영상 가이드: 로그인 방법 보기

처음이신가요? 관리자로부터 초대 메일을 받으셨다면, 메일 내 링크를 클릭하여 계정을 생성해 주세요.

회원가입

초대 메일을 받은 후 계정을 생성하는 과정입니다.

회원가입 페이지

🎬 영상 가이드: 회원가입 방법 보기

계정 상태

비밀번호 찾기

비밀번호를 잊으셨나요?
1. 로그인 화면에서 "비밀번호 찾기" 링크를 클릭하세요.
2. 가입한 이메일 주소를 입력하면 재설정 링크가 발송됩니다.

🎬 영상 가이드: 비밀번호 재설정 방법 보기

3. 시스템 구조 및 흐름

Gatrix와 클라이언트, 게임 서버 간의 상호작용 흐름입니다.

Gatrix 시스템 아키텍처 다이어그램

4. 인터페이스 둘러보기

메인 화면 구성

대시보드 전체 구성

영역 설명
상단 헤더 로고, 환경 선택기, 알림, 프로필 메뉴
좌측 사이드바 메인 네비게이션 메뉴
중앙 콘텐츠 현재 페이지의 주요 내용

환경 선택기 (Environment Selector)

상단 헤더의 환경 선택기는 매우 중요합니다. 현재 작업 중인 환경이 어디인지 항상 확인하세요.

⚠️ 중요: 운영 환경(Production)에서의 변경 사항은 즉시 실제 유저들에게 반영됩니다. 작업 전에 반드시 상단의 환경 이름을 확인하세요!

사이드바 메뉴

관리자 패널 메뉴

게임 관리 메뉴

공통 기능

목록 및 테이블

대부분의 관리 페이지는 데이터 목록을 보여줍니다.
- 검색: 이름이나 ID로 항목을 찾습니다.
- 필터: 상태, 날짜 등으로 목록을 좁혀서 봅니다.
- 정렬: 컬럼 제목을 클릭하여 오름차순/내림차순 정렬합니다.

액션 버튼

버튼 설명
+ 생성 / 추가 새로운 항목을 만듭니다.
수정 (연필 아이콘) 기존 내용을 변경합니다.
삭제 (휴지통 아이콘) 항목을 삭제합니다. (주의 필요)
새로고침 최신 데이터로 목록을 갱신합니다.

시작하기 팁

  1. 내 권한 확인: 본인에게 부여된 권한에 따라 메뉴가 보이거나 안 보일 수 있습니다. 필요한 메뉴가 없다면 관리자에게 요청하세요.
  2. 개발 환경 활용: 익숙하지 않은 기능은 Development 환경에서 먼저 테스트해 보세요.
  3. 저장 습관: 내용을 수정하고 반드시 [저장] 버튼을 눌러야 반영됩니다.
  4. 환경 확인: 작업 전 상단의 환경 선택기를 반드시 확인하세요. Production에서의 실수는 즉시 유저에게 영향을 줍니다.

다국어(로컬라이징) 메시지 안내

Gatrix는 공지사항, 점검 메시지, 팝업 등에서 다국어 메시지를 지원합니다.

다국어 메시지가 필요한 경우

단일 국가 서비스 시

💡 단일 국가에서만 서비스하는 경우, 다국어 메시지 설정은 필요하지 않습니다.

서비스 지역 다국어 메시지 권장 설정
한국 단독 불필요 기본 메시지만 입력
한국 + 일본 필요 한국어/일본어 입력
글로벌 필수 주요 언어 모두 입력

동영상 가이드 모음

주요 기능별 동영상 가이드입니다. 각 영상을 클릭하여 재생할 수 있습니다.

🔐 로그인

🎬
동영상 보기: 00-login

클릭하여 새 창에서 재생하세요.

📝 회원가입

🎬
동영상 보기: 01-register

클릭하여 새 창에서 재생하세요.

🔑 비밀번호 재설정

🎬
동영상 보기: 02-resetpassword

클릭하여 새 창에서 재생하세요.

다음 장: 제 2장: 대시보드 개요 →

제 2장: 대시보드 개요 (Dashboard Overview)

로그인 후 가장 먼저 만나는 화면이 바로 대시보드입니다. 현재 게임 서비스의 주요 지표와 상태를 한눈에 파악할 수 있도록 구성되어 있습니다.

대시보드 화면 구성

대시보드 화면

1. 환영 문구 및 개인 정보

상단에는 접속 시간에 따른 환영 인사와 로그인한 사용자의 이름, 역할(Admin/User)이 표시됩니다.

2. 주요 통계 카드 (Statistics Cards)

현재 환경의 주요 데이터 현황을 숫자로 보여줍니다. 각 카드를 클릭하면 해당 관리 페이지로 바로 이동합니다.

3. 빠른 작업 (Quick Actions)

자주 사용하는 기능으로 바로 이동할 수 있는 단축 버튼입니다.

기능 설명
공지사항 (Service Notices) 새로운 공지사항을 작성하거나 관리합니다.
점검 (Maintenance) 긴급 점검을 설정하거나 예정된 점검을 확인합니다.
쿠폰 (Coupons) 새로운 프로모션 쿠폰을 생성합니다.
클라이언트 버전 앱 업데이트 정책을 변경합니다.

4. 환경별 데이터 현황

운영 중인 모든 환경(Dev, Stage, Prod 등)의 데이터 개수를 요약해서 보여줍니다. 특정 환경에 데이터가 누락되지 않았는지 비교할 때 유용합니다.

5. 최근 활동 내역 (Recent Activities)

누가, 언제, 무엇을 변경했는지 실시간 로그를 보여줍니다.
예: "관리자A님이 '주말 이벤트' 공지사항을 수정했습니다. (5분 전)"

팁: 더 자세한 전체 로그가 필요하다면 관리 > 감사 로그 (Audit Logs) 메뉴를 이용하세요.

6. 클라이언트 크래시 요약 (Crash Events)

최근 플레이어들에게 발생한 앱 충돌(Crash) 리포트 현황을 보여줍니다. 갑작스러운 크래시 증가를 모니터링하여 신속하게 대응할 수 있습니다.

7. 서버 라이프사이클 (Server Lifecycle)

현재 백엔드 서버들의 상태 신호(Heartbeat)를 보여줍니다.
- 🟢 Ready: 정상 작동 중
- 🔴 Stopped: 중지됨
- 🟡 Starting: 시작 중

8. 점검 상태 알림

현재 점검 중인 경우, 대시보드 상단에 "점검 중 (MAINTENANCE)" 배너가 큼지막하게 표시됩니다. 실수로 운영 중인 줄 알고 데이터를 조작하는 일을 방지해 줍니다.

대시보드 개인화

테마 변경 (다크 모드)

눈의 피로를 줄이기 위해 다크 모드를 지원합니다.

설정 화면

  1. 우측 상단 프로필 아이콘 클릭
  2. 설정 (Settings) 선택
  3. 테마(Theme)에서 Dark 또는 Light 선택

언어 변경

대시보드 UI 언어를 변경할 수 있습니다.
1. 우측 상단 프로필 아이콘 클릭
2. 설정 (Settings) 선택
3. 언어(Language)에서 한국어, English, 中文 중 선택

💡 참고: 대시보드에 표시되는 데이터는 현재 상단에서 선택된 환경(Environment)에 대한 데이터입니다. 다른 환경의 현황을 보고 싶다면 상단 환경 선택기를 변경하세요.

이전 장: ← 제 1장: 소개
다음 장: 제 3장: 사용자 관리 →

제 2-1장: 환경 관리 (Environment Management)

Gatrix는 여러 환경(Environment)을 지원하여 개발, 테스트, 운영을 효과적으로 분리할 수 있습니다. 이 장에서는 환경별 데이터 격리와 공유 정책, 그리고 환경 혼동을 방지하는 방법을 설명합니다.

1. 환경이란?

환경(Environment)은 독립된 데이터 공간입니다. 각 환경은 별도의 게임 서버, 설정, 콘텐츠를 가질 수 있습니다.

일반적인 환경 구성

일반적인 환경 구성

flowchart LR
    subgraph 개발["🔧 Development"]
        A[개발 테스트용<br/>데이터 자유롭게 수정]
    end

    subgraph 스테이징["🧪 Staging"]
        B[배포 전 최종 확인<br/>운영과 유사한 환경]
    end

    subgraph 리뷰["📱 Review"]
        C[스토어 심사용<br/>앱스토어/구글플레이]
    end

    subgraph 운영["🚀 Production"]
        D[실제 유저 서비스<br/>⚠️ 변경 시 즉시 반영!]
    end

    개발 --> 스테이징 --> 운영
    스테이징 --> 리뷰

    style D fill:#ffcdd2
환경 용도 주의 수준
Development 새 기능 개발 및 테스트 🟢 낮음
Staging 배포 전 최종 검증 🟡 중간
Review 스토어 심사팀 접속용 🟡 중간
CBT 클로즈드 베타 테스트 🟡 중간
Production 실제 유저 서비스 🔴 높음

2. 환경 선택기

상단 헤더의 환경 선택 드롭다운에서 현재 작업 환경을 선택합니다.

환경 선택 확인 경고

⚠️ 경고: 환경 선택을 확인하지 않고 작업하면, 테스트용 데이터가 운영 환경에 등록되거나, 운영 데이터가 삭제되는 심각한 사고가 발생할 수 있습니다!

3. 환경별 데이터 격리 정책

🔒 환경별로 격리되는 데이터 (독립적)

아래 데이터는 각 환경마다 별도로 관리됩니다. 한 환경에서 수정해도 다른 환경에 영향을 주지 않습니다.

데이터 설명
클라이언트 버전 환경별로 다른 버전 정책 가능
게임 월드 환경별 서버 목록
서비스 점검 환경별 점검 상태
공지사항 환경별 공지 내용
인게임 팝업 환경별 팝업 설정
쿠폰 환경별 쿠폰 발행
배너 환경별 배너 설정
기획 데이터 환경별 데이터 버전
리모트 컨피그 환경별 설정 값

데이터 격리 및 공유 구조

flowchart TB
    subgraph Dev["Development"]
        A1[클라이언트 버전]
        A2[공지사항]
        A3[쿠폰]
    end

    subgraph Prod["Production"]
        B1[클라이언트 버전]
        B2[공지사항]
        B3[쿠폰]
    end

    A1 -.->|❌ 공유 안됨| B1
    A2 -.->|❌ 공유 안됨| B2
    A3 -.->|❌ 공유 안됨| B3

    style Dev fill:#e3f2fd
    style Prod fill:#ffcdd2

🌐 환경과 무관하게 공유되는 데이터 (전역)

아래 데이터는 모든 환경에서 공유됩니다. 한 곳에서 수정하면 모든 환경에 반영됩니다.

데이터 설명
사용자 계정 운영자 계정은 전역으로 관리
환경 접근 권한 사용자별 환경 접근 권한은 전역 설정
API 토큰 환경 지정은 있지만 토큰 목록은 전역 조회
감사 로그 모든 환경의 활동이 통합 기록
화이트리스트 환경별로 별도 관리 가능하나 설정에 따라 공유 
flowchart TB
    subgraph 전역["🌐 전역 데이터"]
        U[사용자 계정]
        A[감사 로그]
        T[API 토큰]
    end

    subgraph Dev["Development"]
        D1[환경 데이터]
    end

    subgraph Prod["Production"]
        P1[환경 데이터]
    end

    전역 --> Dev
    전역 --> Prod

    style 전역 fill:#c8e6c9

4. 환경 혼동 방지 가이드

❌ 흔한 실수 사례

실수 결과 예방법
Production에서 테스트 공지 등록 실제 유저에게 테스트 문구 노출 환경 확인 후 작업
Dev에서 작업 후 Prod 미등록 운영에 콘텐츠 누락 체크리스트 사용
Prod에서 데이터 삭제 테스트 실제 데이터 영구 삭제 Dev에서 테스트
환경별 쿠폰 코드 혼동 잘못된 코드 배포 환경 명시 습관

✅ 환경 혼동 방지 체크리스트

작업 전:
- [ ] 상단 환경 선택기에서 현재 환경 확인
- [ ] Production인 경우 정말 필요한 작업인지 재확인
- [ ] 대용량 작업 시 먼저 Dev에서 테스트

작업 후:
- [ ] 의도한 환경에 데이터가 등록되었는지 확인
- [ ] 다른 환경에 잘못 등록되지 않았는지 확인
- [ ] Production 작업 시 팀원에게 공유

💡 환경 구분 팁

  1. 색상 구분: Production 환경은 빨간색 테두리로 표시됩니다.
  2. 이름 확인: 환경 선택기의 텍스트를 소리 내어 읽어보세요.
  3. 작업 로그: 중요 작업 시 사내 메신저에 "Production에서 OO 작업 시작" 알림

5. 환경 간 데이터 복사

일부 데이터는 환경 간 복사가 가능합니다.

복사 가능한 항목

항목 방법
클라이언트 버전 목록에서 복사 버튼 → 대상 환경에서 붙여넣기
공지사항 수동으로 내용 복사 후 재등록
기획 데이터 동일 파일을 각 환경에 업로드

복사 시 주의사항

6. 환경별 권한 관리

사용자마다 접근 가능한 환경을 제한할 수 있습니다.

flowchart TD
    A[신규 입사자] --> B[Development만 접근]
    B --> C[업무 숙련]
    C --> D[Staging 접근 추가]
    D --> E[Production 접근 승인]

    style B fill:#c8e6c9
    style E fill:#ffcdd2

권한 설정 예시

역할 Development Staging Review Production
신규 운영자 ✅ ❌ ❌ ❌
일반 운영자 ✅ ✅ ✅ ❌
시니어 운영자 ✅ ✅ ✅ ✅
관리자 ✅ ✅ ✅ ✅

💡 권장: 신규 입사자는 처음 1~2주간 Development만 접근하도록 설정하여 실수를 방지하세요.

7. 환경 추가/편집/삭제

환경을 직접 추가, 수정, 삭제할 수 있습니다.

경로: 설정 (Settings) → 환경 관리 (Environment Management)
필요 권한: environments.manage

환경 목록 화면

환경 관리 목록

테이블 컬럼 설명

컬럼 설명
환경 이름 시스템 내부 식별자 (예: development, production)
표시 이름 대시보드에 표시되는 이름
환경 타입 Development / Staging / Production
설명 환경에 대한 부가 설명
기본 환경 새 사용자의 기본 접속 환경
시스템 정의 시스템에서 자동 생성한 환경 여부
승인 필요 변경 시 승인 프로세스 필요 여부
표시 환경 선택기에 표시 여부
작업 ✏️ 편집, 🗑️ 삭제 버튼

환경 추가하기

[환경 추가] 버튼을 클릭하여 새 환경을 생성합니다.

환경 추가 폼

입력 항목

항목 필수 설명
환경 이름 ✅ 시스템 내부 식별자 (영문, 소문자, 언더스코어만 사용)
표시 이름 ✅ 대시보드에 표시될 이름
환경 타입 ✅ Development / Staging / Production 중 선택
설명 환경 용도에 대한 설명
베이스 환경 기존 환경의 데이터를 복사할 경우 선택
승인 필요 설정 이 환경에서 변경 시 승인 절차 필요 여부

💡 베이스 환경 기능: 새 환경 생성 시 기존 환경을 선택하면, 해당 환경의 데이터(월드, 세그먼트, 템플릿 등)가 복사됩니다.

환경 편집하기

목록에서 [✏️ 편집] 버튼을 클릭하여 환경 설정을 수정합니다.

환경 편집 폼

수정 가능한 항목

항목 설명
환경 이름 변경 불가 (시스템 식별자)
표시 이름 대시보드 표시명 변경 가능
설명 환경 설명 변경
환경 타입 Development / Staging / Production 변경
색상 환경 구분용 색상 코드 (예: #4CAF50)
승인 필요 설정 승인 프로세스 활성화/비활성화

⚠️ 주의: Production 환경의 설정을 변경할 때는 신중하게 진행하세요.

환경 삭제하기

목록에서 [🗑️ 삭제] 버튼을 클릭하여 환경을 삭제합니다.

⚠️ 경고: 환경을 삭제하면 해당 환경의 모든 데이터(클라이언트 버전, 공지사항, 쿠폰 등)가 영구 삭제됩니다! 복구할 수 없습니다.

삭제 전 확인 사항:
- [ ] 해당 환경에 중요 데이터가 없는지 확인
- [ ] 백업이 필요한 데이터는 미리 내보내기
- [ ] 다른 팀원에게 삭제 사실 공유

환경 복사하기

기존 환경의 데이터를 포함한 새 환경을 빠르게 생성할 수 있습니다.

  1. 환경 목록에서 [복사] 버튼 클릭
  2. 새 환경 이름 입력
  3. 복사할 데이터 범위 선택
  4. [생성] 클릭

8. 자주 묻는 질문 (FAQ)

Q: 환경을 새로 추가하려면 어떻게 하나요?

A: 설정 → 환경 관리에서 [환경 추가] 버튼을 클릭하여 새 환경을 생성할 수 있습니다. environments.manage 권한이 필요합니다.

Q: 실수로 Production에 테스트 데이터를 넣었어요!

A: 즉시 해당 데이터를 비활성화하거나 삭제하세요. 그리고 감사 로그에서 영향 범위를 확인하고 팀에 공유하세요.

Q: Dev에서 작업한 내용을 Prod에 일괄 적용할 수 있나요?

A: 현재는 자동 동기화 기능이 없습니다. 각 환경에서 개별적으로 등록해야 합니다. 단, 새 환경 생성 시 베이스 환경을 선택하면 데이터를 복사할 수 있습니다.

Q: 환경 삭제 시 데이터가 복구 가능한가요?

A: 아니요, 환경 삭제 시 해당 환경의 모든 데이터가 영구 삭제됩니다. 삭제 전 반드시 백업하세요.

Q: "승인 필요" 설정은 무엇인가요?

A: 이 설정을 활성화하면, 해당 환경에서 데이터 변경 시 상위 관리자의 승인이 필요합니다. Production 환경에 권장되는 설정입니다.

이전 장: ← 제 2장: 대시보드 개요
다음 장: 제 3장: 사용자 관리 →

제 3장: 사용자 관리 (User Management)

사용자 관리는 대시보드에 접속할 수 있는 운영자 계정을 관리하고 권한을 제어하는 기능입니다. 이 챕터에서는 단순한 기능 설명을 넘어, 입사/퇴사 등 실제 업무 상황에서의 처리 절차를 안내합니다.

경로: 관리 (Admin) → 사용자 (Users)
필요 권한: users.manage (수정 시), users.view (조회 시)

🎬 영상 가이드: 사용자 관리 방법 보기

1. 화면 구성

사용자 관리 페이지의 전체 화면입니다.

3.1 초대 기반 가입 프로세스

sequenceDiagram
    participant Admin as 기존 관리자
    participant System as Gatrix 시스템
    participant User as 신규 사용자

    Admin->>System: 1. 초대장 발송 (이메일 입력)
    System->>User: 2. 초대 이메일 전송 (링크 포함)
    User->>System: 3. 링크 클릭 및 회원가입 양식 작성
    System->>User: 4. 가입 완료 및 로그인

상단 툴바 버튼 설명

버튼 설명
사용자 추가 이름, 이메일, 비밀번호를 직접 입력하여 계정을 즉시 생성합니다.
새 초대 생성 이메일로 초대 링크를 발송합니다. 사용자가 직접 가입하도록 유도할 때 사용합니다.

⚠️ 중요: SMTP 설정 필수

이메일 발송 기능(초대장 발송, 비밀번호 재설정 등)을 사용하려면 SMTP 서버 설정이 올바르게 되어 있어야 합니다.
SMTP가 설정되지 않은 경우 이메일이 발송되지 않으며, 이 기능을 사용할 수 없습니다.

🔧 관리자 가이드: 상세 설정 방법은 부록 A: 시스템 설정 가이드를 참고하세요.

테이블 컬럼 설명

컬럼 설명
사용자 사용자 이름 (프로필 사진 포함)
이메일 로그인에 사용하는 이메일 주소
이메일 인증 이메일 인증 완료 여부
역할 관리자(Admin) 또는 사용자(User)
상태 활성(Active), 대기(Pending), 정지(Suspended)
환경 접근 권한 접근 가능한 환경 목록 (Dev, Staging, Production 등)
태그 분류용 태그
가입일 계정 생성 일시
마지막 로그인 최근 접속 일시
작업 ✏️ 편집, 🗑️ 삭제 버튼

2. 역할(Role) 및 권한 구조

Gatrix의 권한 시스템은 역할(Role)과 세부 권한(Permissions)의 조합으로 이루어집니다.

역할 (Role)

사용자의 기본적인 등급을 결정합니다.

역할 설명 추천 대상
User (사용자) 기본 사용자. 조회(View) 기능 위주입니다. 데이터를 수정하거나 삭제할 수 없습니다. 신규 입사자, 단순 모니터링 담당자, 타 부서 참관인
Admin (관리자) 관리자. 대부분의 수정(Edit) 권한을 가질 수 있습니다. 게임 운영자, 사업 PM, QA 담당자, 개발자

세부 권한 (Permissions)

Admin 역할이라도 모든 것을 할 수 있는 것은 아닙니다. 업무에 필요한 권한만 부여하세요.

사용자 편집 - 권한 설정

주요 권한 목록:

권한 설명 추천 대상
users.manage 동료 계정을 생성/수정/삭제 팀장급
game-worlds.manage 서버 상태 변경 서버/인프라 담당
coupons.manage 쿠폰 발행 사업/마케팅 담당
service-notices.manage 공지사항 작성 운영자
audit-logs.view 감사 로그 조회 보안 담당
maintenance.manage 점검 관리 서버/인프라 담당

💡 원칙: "권한은 최소한으로 주고, 필요할 때 늘린다" (Principle of Least Privilege)

3. 사용자 추가 방법

방법 1: 직접 추가

관리자가 직접 계정을 생성합니다.

사용자 직접 추가 폼

입력 항목:

항목 필수 설명
이름 ✅ 사용자의 표시 이름
이메일 ✅ 로그인에 사용할 이메일 주소
비밀번호 ✅ 8자 이상의 안전한 비밀번호
역할 ✅ 관리자(Admin) 또는 사용자(User)
태그 분류용 태그 (복수 선택 가능)
권한 채널 세부 권한 설정

방법 2: 초대 링크 발송

사용자가 직접 가입하도록 초대합니다.

새 초대 생성 폼

입력 항목:

항목 필수 설명
이메일 ✅ 초대할 이메일 주소 (복수 입력 가능)
만료 시간 초대 링크 유효 기간 (기본: 48시간)

4. 상황별 업무 가이드 (Scenarios)

상황 A: 신규 운영자 입사 시 (온보딩)

신규 GM '홍길동'님이 입사했습니다.

flowchart TD
    A[신규 입사자] --> B{계정 생성 방식}
    B -->|직접 생성| C[관리자가 생성]
    B -->|초대 발송| D[초대 링크 발송]
    C --> E[계정 활성화]
    D --> F[사용자 가입]
    F --> E
    E --> L[업무 시작]

    style A fill:#e3f2fd
    style L fill:#c8e6c9

상세 절차:

  1. [사용자 추가] 또는 [새 초대 생성] 버튼 클릭
  2. 이메일: gildong.hong@company.com 입력
  3. 역할: 초기 적응을 위해 User 역할 부여 권장 (실수 방지)
  4. 초대 방식의 경우, 링크를 복사하여 메신저로 전달
  5. 홍길동님이 링크를 통해 가입 완료
  6. 관리자가 목록에서 Pending → Active로 변경
  7. 업무에 익숙해지면 Admin으로 승격 및 필요한 세부 권한 추가

상황 B: 담당자가 휴가/출장 갔을 때

특정 담당자만의 권한이 필요할 때 (예: 쿠폰 발행 권한이 김철수님에게만 있는데 휴가를 감)

flowchart LR
    A[담당자 휴가] --> B[❌ 비밀번호 공유 절대 금지!]
    A --> C[✅ 대행자 계정에 임시 권한 부여]
    C --> D[휴가 복귀 후 권한 회수]

    style B fill:#ffcdd2
    style C fill:#c8e6c9

상황 C: 운영자 퇴사 시 (오프보딩)

보안 사고 방지를 위해 퇴사 즉시 접근을 차단해야 합니다.

flowchart TD
    A[퇴사 통보] --> B[사용자 목록에서 퇴사자 검색]
    B --> C[상태를 'Suspended' 로 변경]
    C --> D[즉시 로그아웃됨]
    D --> E[모든 권한 체크박스 해제]
    E --> F[1~3개월 후 계정 삭제]

    style A fill:#ffcdd2
    style C fill:#fff9c4
    style F fill:#e0e0e0

    G[⚠️ 주의: 바로 삭제하지 마세요!]
    G --> H[삭제하면 Audit Log에서<br/>'알 수 없는 사용자'로 표시됨]

    style G fill:#ffcdd2

상세 절차:

  1. 사용자 목록에서 퇴사자 검색
  2. 일시정지 (Suspend) 버튼 클릭 → 즉시 로그아웃됨
  3. 모든 권한 체크박스 해제
  4. ⚠️ 중요: 계정을 바로 삭제하지 마세요. 삭제하면 과거 로그(Audit Log)에서 퇴사자의 이름이 사라져서 "알 수 없는 사용자"로 표시됩니다. 1~3개월 후 삭제하는 것이 좋습니다.

5. 환경 접근 권한 관리

특정 사용자에게 특정 환경만 접근하도록 제한할 수 있습니다.

환경 설명 접근 허용 대상
Development 개발 환경 개발자, QA
Staging 스테이징 환경 QA, 운영자
Production 운영 환경 (실제 유저) 승인된 운영자만
Review 스토어 심사용 환경 심사 담당자
CBT 클로즈드 베타 환경 CBT 담당자

💡 팁: 신규 입사자는 먼저 Development 환경만 접근하도록 설정하고, 익숙해진 후 Production 접근 권한을 부여하세요.

6. 자주 묻는 질문 (FAQ) & 문제 해결

Q: 초대 메일이 안 온다고 합니다.

A: 스팸 메일함을 먼저 확인해 주세요. 그래도 없다면, 초대 링크의 유효기간이 만료되었을 수 있습니다. 기존 초대를 삭제하고 다시 초대를 생성하여 링크를 직접 메신저로 전달해 주세요.

Q: 갑자기 "권한이 없습니다(403 Forbidden)"라고 뜹니다.

A: 다음을 확인하세요.
1. 관리자가 귀하의 권한 설정을 변경했을 수 있습니다.
2. 접속하려는 환경(Environment)에 대한 접근 권한이 없을 수도 있습니다.
3. 팀장님께 문의하세요.

Q: 실수로 동료 계정을 정지시켰습니다.

A: 당황하지 마세요. 목록에서 해당 사용자를 찾아 상태를 다시 Active로 변경하면 즉시 복구됩니다.

Q: 비밀번호를 5회 틀려서 잠겼다고 합니다.

A: 보안 정책상 잠긴 것입니다. 관리자 화면에서 해당 사용자의 편집 버튼을 클릭하고 [비밀번호 초기화 메일 발송]을 눌러주세요.

7. 권한 관리 체크리스트

신규 입사자 온보딩 체크리스트

퇴사자 오프보딩 체크리스트

8. 트러블슈팅 케이스

🔴 케이스 1: 초대 메일이 도착하지 않아요

증상: 초대 링크를 발송했는데 메일을 받지 못함

원인 및 해결:

원인 해결 방법
스팸 메일함 스팸/정크 폴더 확인
메일 주소 오타 이메일 주소 정확히 입력했는지 확인
사내 메일 필터 IT팀에 화이트리스트 요청
초대 유효기간 만료 새 초대 생성 후 직접 링크 공유

🔴 케이스 2: 비밀번호를 잊어버렸어요

증상: 사용자가 비밀번호를 분실하여 로그인 불가

해결 방법:
1. 로그인 페이지 → "비밀번호 찾기" 클릭
2. 등록된 이메일로 재설정 링크 발송
3. 메일 확인 후 새 비밀번호 설정

관리자가 직접 재설정하려면:
1. 사용자 관리 → 해당 사용자 편집
2. [비밀번호 초기화 메일 발송] 클릭

🔴 케이스 3: 권한이 없다고 표시돼요 (403 Forbidden)

증상: 특정 메뉴나 기능에 접근 시 "권한이 없습니다" 오류

원인 및 해결:

원인 해결 방법
해당 권한 미부여 관리자에게 권한 요청
환경 접근 권한 없음 해당 환경 접근 권한 추가
세션 만료 로그아웃 후 재로그인
역할(Role) 부족 User → Admin 승격 필요

9. 동영상 가이드

사용자 관리 전체 흐름

🎬
동영상 보기: 03-usermanagement

클릭하여 새 창에서 재생하세요.

이전 장: ← 제 2장: 대시보드 개요
다음 장: 제 4장: 클라이언트 버전 관리 →

제 4장: 클라이언트 버전 관리 (Client Version Management)

앱 업데이트 시 가장 핵심이 되는 기능입니다. 사용자의 앱 버전과 서버의 허용 버전을 매칭하여 "업데이트를 받을지", "게임을 계속할지"를 결정합니다.

경로: 관리 (Admin) → 클라이언트 버전 (Client Versions)
필요 권한: client-versions.manage

🎬 영상 가이드: 클라이언트 버전 관리 방법 보기

1. 화면 구성

클라이언트 버전 관리 페이지의 전체 화면입니다.

클라이언트 버전 목록 화면

상단 툴바 버튼 설명

화면 상단에는 다음과 같은 버튼들이 있습니다:

번호 버튼 설명
① 내보내기 현재 버전 리스트를 CSV/Excel 파일로 내보냅니다. 백업이나 외부 공유 시 유용합니다.
② 개별 추가 서버 주소, 화이트리스트 설정 등 모든 항목을 직접 지정하여 새 버전을 추가합니다.
③ 간편 추가 버전과 플랫폼만 입력하면 나머지는 기본값을 사용합니다. 빠른 등록에 적합합니다.
④ SDK 연동 가이드 클라이언트 개발자를 위한 API 문서와 테스트 도구를 제공합니다.

테이블 컬럼 설명

컬럼 설명
클라이언트 버전 SemVer 형식의 버전 번호 (예: 1.0.0, 2.1.3)
플랫폼 PC, iOS, Android, HarmonyOS 등 클라이언트 플랫폼
클라이언트 상태 업데이트 정책 상태 (온라인, 강제 업데이트 등)
게임 서버 주소 게임 로직 서버 URL
패치 주소 CDN 또는 패치 다운로드 URL
게스트 모드 허용 비로그인 상태로 게임 가능 여부
태그 분류용 태그 (필터링에 활용)
생성일시 버전 등록 일시
생성자 버전을 등록한 관리자
작업 🔄 복사, ✏️ 편집, 🗑️ 삭제 버튼

필터 및 검색 기능

2. 버전 상태 (Status) 완전 정복

상태를 잘못 설정하면 유저가 게임에 접속하지 못하거나, 심각한 버그가 있는 버전으로 계속 게임을 하게 됩니다.

상태 아이콘 화면 예시 언제 쓰나요?
온라인 🟢 (아무 팝업 없음) 현재 문제가 없는 정상 버전일 때
오프라인 ⚫ "서비스가 종료되었습니다." 서비스 중단 상태
권장 업데이트 🔵 "새로운 기능이 추가되었습니다. [나중에] [업데이트]" 마이너 버그 수정, 편의성 개선 등
강제 업데이트 🟠 "필수 업데이트가 필요합니다. [확인]" 시즌 시작, 치명적 버그 수정 시
리뷰 중 🟡 (심사팀 전용 접속) 스토어 심사 중인 버전
접속불가&패치허용 🟣 "점검 중이지만 패치를 받을 수 있습니다." 게임은 막고 패치만 허용
점검중 🔴 "현재 점검 중입니다." 특정 버전 차단 필요 시

⚠️ 주의: 운영 환경(Production)에서 상태를 변경하면 즉시 실제 유저에게 반영됩니다. 변경 전 반드시 테스트 환경에서 검증하세요.

3. 버전 추가하기

개별 추가 (상세 설정)

[개별 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.

개별 추가 폼

입력 항목 상세 설명

섹션 항목 필수 설명
기본 정보 버전 ✅ SemVer 형식으로 입력 (예: 1.0.0, 2.1.3-beta.1)
플랫폼 ✅ PC, iOS, Android, HarmonyOS 등 선택
상태 라벨 ✅ 위 상태 중 선택 (기본값: 온라인)
서버 주소 게임 서버 주소 ✅ 게임 로직 서버 URL (예: https://game.example.com)
화이트리스트용 게임 서버 주소 테스터/심사팀용 별도 서버 URL
패치 주소 CDN 또는 패치 서버 URL
화이트리스트용 패치 주소 테스터/심사팀용 별도 패치 URL
기타 태그 분류용 태그 (복수 선택 가능)
게스트 모드 허용 비로그인 플레이 허용 여부

화이트리스트 기능이란?

특정 계정 ID 또는 IP 주소를 화이트리스트에 등록하면, 해당 사용자는 일반 서버 대신 화이트리스트용 서버 주소로 연결됩니다.

활용 예시:
- 스토어 심사팀이 새 버전을 테스트할 때 (심사 계정 ID 등록)
- 내부 QA팀이 개발 서버에서 테스트할 때 (사내 IP 등록)
- 베타 테스터에게 별도 서버 제공 시

간편 추가

빠르게 버전만 등록하고 싶을 때 사용합니다.

팁: 기본값을 잘 설정해 두면 간편 추가로 수초 내에 버전 등록이 가능합니다.

4. 플랫폼별 기본값 설정

각 플랫폼에 대해 공통으로 사용할 기본 서버 주소를 미리 설정합니다.

설정 항목:
- 게임 서버 주소 (기본값)
- 패치 주소 (기본값)
- 화이트리스트용 서버 주소 (기본값)

설정된 기본값은 간편 추가 시 자동으로 적용됩니다.

5. SDK 연동 가이드

클라이언트에서 버전 정보를 조회할 수 있는 API를 제공합니다.

API 가이드 탭

[SDK 연동 가이드] 버튼을 클릭하면 아래와 같은 화면이 나타납니다.

SDK 연동 가이드

표시 정보

항목 설명
엔드포인트 GET /api/v1/client/{environment}/client-version
파라미터 platform (필수), version (필수), lang (선택)
필수 헤더 X-Application-Name, X-API-Token, Content-Type
curl 예시 복사하여 터미널에서 바로 테스트 가능

API 테스트 탭

실제 API를 호출해 볼 수 있는 테스트 도구입니다.

API 테스트

테스트 방법

  1. Platform 선택 (ios, android, pc 등)
  2. Version 입력 (예: 1.0.0)
  3. Status, Language 선택 (선택사항)
  4. curl 미리보기에서 명령어 확인
  5. [요청] 버튼 클릭하여 실제 API 호출
  6. 응답 결과 확인

활용 팁: 버전 등록 후 API 테스트 탭에서 올바르게 응답되는지 반드시 확인하세요.

6. 업데이트 배포 시나리오 (Workflow)

신규 버전 1.2.0을 배포하는 상황을 가정해 봅시다.

┌─────────────────────────────────────────────────────────────┐
│                    업데이트 배포 프로세스                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1단계: 스토어 출시                                          │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  구글/애플 스토어에 1.2.0 앱 제출 → 심사 통과 → 출시   │   │
│  └─────────────────────────────────────────────────────┘   │
│                           ↓                                │
│  2단계: Gatrix에 신규 버전 등록                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  버전: 1.2.0 / 상태: 온라인                           │   │
│  │  (기존 1.1.0도 온라인 유지 → 자연스러운 업데이트 유도)   │   │
│  └─────────────────────────────────────────────────────┘   │
│                           ↓                                │
│  3단계: 강제 업데이트 전환                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  1.1.0 상태 → 강제 업데이트로 변경                     │   │
│  │  (구버전 유저는 스토어로 이동됨)                        │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

상세 단계

1단계: 마켓에 앱 제출 및 출시 확인

2단계: Gatrix에 새 버전 등록
1. [개별 추가] 또는 [간편 추가] 클릭
2. 버전: 1.2.0, 상태: 온라인
3. [저장]
4. API 테스트로 정상 응답 확인

3단계: 구버전 강제 업데이트 설정
1. 1.1.0 편집 버튼 클릭
2. 상태를 강제 업데이트로 변경
3. [저장]

7. 긴급 대응 시나리오

상황: 1.2.0 버전에서 치명적 버그 발견!

┌─────────────────────────────────────────────────────────────┐
│                    긴급 롤백 프로세스                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 1.2.0 버전 상태 → 점검중 또는 오프라인으로 변경           │
│                           ↓                                │
│  2. 1.1.0 (구버전) 상태 → 온라인으로 복구                    │
│                           ↓                                │
│  3. 공지사항 등록: "구버전 재설치 안내"                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

대응 메시지 예시:

"버전 1.2.0에서 발견된 오류로 인해 임시로 서비스를 중단합니다. 앱 스토어에서 이전 버전을 재설치해 주시기 바랍니다."

8. 버전 관리 체크리스트

업데이트 배포 전 반드시 확인하세요.

배포 전 체크리스트

리뷰 버전 체크리스트 (스토어 심사 시)

9. 자주 묻는 질문 (FAQ)

Q: 버전을 등록했는데 클라이언트에서 조회가 안 됩니다.

A: 다음을 순서대로 확인하세요.
1. 환경(Environment) 선택이 올바른가요? (상단 헤더 확인)
2. 플랫폼이 정확한가요? (PC, ios, android 등)
3. SDK 가이드 → API 테스트에서 해당 버전을 조회해 보세요.
4. API 토큰이 유효한가요?

Q: 화이트리스트용 서버 주소는 언제 사용되나요?

A: 화이트리스트에 등록된 계정 ID 또는 IP 주소로 접속하면 화이트리스트용 서버 주소가 반환됩니다.

활용 사례:
- 스토어 심사팀 테스트 (심사 계정 ID 등록)
- 내부 QA팀 개발 서버 접속 (사내 IP 등록)
- 베타 테스터 전용 서버 제공 (테스터 계정 ID 등록)

Q: 간편 추가와 개별 추가의 차이는 무엇인가요?

구분 간편 추가 개별 추가
입력 항목 버전, 플랫폼 모든 항목
서버 주소 플랫폼별 기본값 사용 직접 입력
화이트리스트 기본값 사용 직접 설정 가능
적합한 경우 빠른 등록 상세 커스터마이징

Q: 버전 복사 기능은 무엇인가요?

A: 기존 버전의 모든 설정을 복사하여 새 버전을 생성합니다. 버전 번호만 변경하면 되어 반복 작업 시 편리합니다.

10. 트러블슈팅 케이스

🔴 케이스 1: 버전을 등록했는데 클라이언트에서 조회가 안 돼요

증상: API 테스트에서도 버전 정보가 조회되지 않음

원인 및 해결:

원인 해결 방법
환경(Environment) 불일치 올바른 환경에 등록했는지 확인
플랫폼 불일치 ios, android, pc 등 정확한 플랫폼 확인
버전 형식 오류 SemVer 형식(1.0.0) 준수 확인
API 토큰 문제 유효한 토큰인지 확인

🔴 케이스 2: 강제 업데이트를 설정했는데 팝업이 안 떠요

증상: 구버전을 강제 업데이트로 설정했는데 유저에게 팝업 미표시

원인 및 해결:

원인 해결 방법
클라이언트 SDK 미구현 개발팀에 버전 체크 로직 확인 요청
스토어 URL 미설정 업데이트 버튼 클릭 시 이동할 URL 설정
캐싱 문제 앱 완전 종료 후 재시작, 5분 대기
잘못된 버전 선택 현재 유저가 사용하는 정확한 버전 확인

🔴 케이스 3: 스토어 심사팀이 접속을 못해요

증상: 앱스토어/구글플레이 심사팀이 게임 접속 불가

원인 및 해결:

원인 해결 방법
리뷰 버전 미등록 Review 환경에 해당 버전 등록
상태가 "리뷰 중" 아님 상태를 "리뷰 중"으로 변경
화이트리스트 누락 심사 계정 ID를 화이트리스트에 추가
서버 주소 오류 화이트리스트용 서버 주소 확인

11. 동영상 가이드

클라이언트 버전 관리 전체 흐름

🎬
동영상 보기: 04-clientversions

클릭하여 새 창에서 재생하세요.

이전 장: ← 제 3장: 사용자 관리
다음 장: 제 5장: 게임 월드 관리 →

제 5장: 게임 월드 관리 (Game World Management)

게임의 월드(서버) 목록을 관리하고 점검 상태를 제어하는 기능입니다. 유저가 게임에 접속할 때 보게 되는 서버 목록이 여기서 관리됩니다.

경로: 관리 (Admin) → 게임 월드 (Game Worlds)
필요 권한: game-worlds.manage

🎬 영상 가이드: 게임 월드 관리 방법 보기

1. 화면 구성

게임 월드 관리 페이지의 전체 화면입니다.

게임 월드 목록 화면

상단 툴바 버튼 설명

버튼 설명
게임 월드 추가 새로운 게임 월드(서버)를 등록합니다.
SDK 연동 가이드 클라이언트에서 월드 목록을 조회하는 API 문서를 제공합니다.

테이블 컬럼 설명

컬럼 설명
월드 ID 시스템에서 사용하는 고유 식별자 (예: UWO-RELCN-01)
이름 유저에게 표시되는 월드 이름
설명 월드에 대한 부가 설명
월드 서버 주소 게임 로직 서버 URL
표시 여부 유저에게 월드 목록에 노출될지 여부
점검 여부 현재 점검 중인지 여부
태그 분류용 태그
생성일 월드 등록 일시
생성자 월드를 등록한 관리자
작업 📋 복사, ✏️ 편집, 🗑️ 삭제 버튼

2. 월드 상태 (Status)

월드는 다음 상태들을 가질 수 있습니다.

stateDiagram-v2
    [*] --> Normal: 월드 생성
    Normal --> Maintenance: 점검 시작
    Maintenance --> Normal: 점검 종료
    Normal --> Hidden: 숨김 처리
    Hidden --> Normal: 표시 전환

    state Normal {
        [*] --> Visible
        Visible: 🟢 유저에게 표시
    }

    state Maintenance {
        [*] --> InProgress
        InProgress: 🔴 점검 중
        note right of InProgress: 유저 접속 차단
    }

    state Hidden {
        [*] --> Invisible
        Invisible: ⚪ 숨김 상태
    }
상태 아이콘 설명
표시 (Visible) 🟢 유저에게 월드 목록에 노출됩니다.
숨김 (Hidden) ⚪ 유저에게 보이지 않습니다. 개발 중인 월드에 적합합니다.
정상 (Normal) 🟢 유저 접속이 가능한 상태입니다.
점검 중 (Maintenance) 🔴 점검 중인 상태로, 유저 접속이 차단됩니다.

3. 게임 월드 추가하기

[게임 월드 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.

게임 월드 추가 폼

기본 정보 탭

항목 필수 설명
월드 ID ✅ 고유한 월드 식별자 (예: UWO-RELCN-01)
이름 ✅ 유저에게 표시되는 월드 이름
설명 월드에 대한 부가 설명
월드 서버 주소 ✅ 게임 로직 서버 URL (예: 127.0.0.1:10000)
태그 분류용 태그
사용자에게 표시 이 월드를 유저에게 표시할지 여부
점검 중 점검 모드 설정 시 체크
커스텀 페이로드 JSON 형식의 추가 데이터 (클라이언트에 전달됨)

인프라 설정 탭

고급 서버 및 인프라 설정을 JSON 형식으로 관리할 수 있습니다.

4. 점검 설정 (Maintenance)

월드별로 점검 상태를 설정하여 유저 접속을 제어할 수 있습니다.

flowchart TD
    A[점검 모드 활성화] --> B{강제 접속 종료?}
    B -->|예| C[유예 시간 경고 표시]
    B -->|아니오| D[새 접속만 차단]
    C --> E[유예 시간 경과]
    E --> F[접속 중인 유저 강제 종료]
    D --> G[기존 유저는 계속 플레이 가능]
    F --> H[점검 완료까지 대기]
    G --> H
    H --> I[점검 종료 - 접속 재개]

    style A fill:#ffcdd2
    style I fill:#c8e6c9

점검 설정 항목

항목 설명
점검 기간 점검 시작 시간과 종료 시간
점검 메시지 유저 접속 시도 시 표시할 안내 메시지
다국어 지원 한국어, 영어, 중국어 등 언어별 메시지 설정
강제 접속 종료 점검 시작 시 접속 중인 유저 강제 퇴장 여부
유예 시간 강제 종료 전 경고 메시지 표시 시간 (분)

5. 월드 순서 변경

월드 목록에서 드래그 핸들을 이용하여 월드의 노출 순서를 변경할 수 있습니다.

💡 팁: 신규 월드나 이벤트 월드를 상단에 배치하여 유저의 관심을 유도할 수 있습니다.

6. SDK 연동 가이드

클라이언트에서 월드 목록을 조회할 수 있는 API를 제공합니다.

SDK 연동 가이드

API 엔드포인트

GET /api/v1/client/{environment}/game-worlds

API 테스트

SDK 가이드의 API 테스트 탭에서 직접 API를 호출하여 응답을 확인할 수 있습니다.

7. 운영 시나리오

시나리오: 신규 월드 오픈

flowchart LR
    A[월드 생성<br/>숨김 상태] --> B[테스트 및<br/>QA 진행]
    B --> C[공지사항<br/>작성]
    C --> D[오픈 시간에<br/>표시 전환]
    D --> E[모니터링]

    style A fill:#e3f2fd
    style D fill:#c8e6c9
  1. 월드 생성 (숨김 상태로) - 개발팀에서 새 월드 등록
  2. 테스트 - QA팀에서 접속 테스트 진행
  3. 공지사항 작성 - 신규 월드 오픈 안내
  4. 표시 전환 - 오픈 시간에 맞춰 "사용자에게 표시" 활성화
  5. 모니터링 - 유저 접속 상황 확인

시나리오: 긴급 점검

flowchart TD
    A[서버 장애 발생] --> B[월드 편집<br/>점검 중 활성화]
    B --> C[강제 접속 종료<br/>설정]
    C --> D[점검 메시지<br/>입력]
    D --> E[공지사항<br/>등록]
    E --> F[문제 해결]
    F --> G[점검 종료<br/>접속 재개]

    style A fill:#ffcdd2
    style G fill:#c8e6c9

8. 자주 묻는 질문 (FAQ)

Q: 월드를 숨겼는데 기존 접속자는 어떻게 되나요?

A: "사용자에게 표시" 옵션은 목록 노출만 제어합니다. 이미 접속 중인 유저는 영향을 받지 않습니다. 접속을 차단하려면 "점검 중" 옵션을 사용하세요.

Q: 점검 시간을 예약할 수 있나요?

A: 현재 버전에서는 수동으로 점검 모드를 전환해야 합니다. 예약 기능이 필요하면 전체 점검 관리 메뉴를 활용하세요.

Q: 커스텀 페이로드는 어떻게 사용하나요?

A: JSON 형식으로 추가 데이터를 입력하면, 클라이언트에서 월드 목록 조회 시 함께 전달됩니다. 예: {"event": "summer_festival", "maxPlayers": 5000}

9. 트러블슈팅 케이스

🔴 케이스 1: 월드를 등록했는데 게임에서 안 보여요

증상: 대시보드에서 월드를 등록했으나 게임 내 서버 목록에 표시되지 않음

원인 및 해결:

원인 해결 방법
"사용자에게 표시" 비활성화 토글 상태 확인
환경 불일치 Production 환경에 등록했는지 확인
점검 중 상태 점검 중이면 숨김 처리될 수 있음
캐싱 문제 앱 재시작 또는 5분 대기

🔴 케이스 2: 월드 순서가 변경되지 않아요

증상: 드래그로 순서를 변경했는데 저장 후에도 반영되지 않음

원인 및 해결:

원인 해결 방법
저장 버튼 미클릭 순서 변경 후 [저장] 클릭 필수
새로고침 없이 확인 페이지 새로고침 후 재확인
권한 부족 game-worlds.manage 권한 확인

10. 동영상 가이드

게임 월드 관리 전체 흐름

🎬
동영상 보기: 05-gameworlds

클릭하여 새 창에서 재생하세요.

이전 장: ← 제 4장: 클라이언트 버전 관리
다음 장: 제 6장: 점검 관리 →

제 6장: 점검 관리 (Maintenance Management)

점검은 유저들에게 가장 큰 불편을 주는 작업이므로, 정확한 시간 안내와 안정적인 종료가 생명입니다.

🎬 영상 가이드: 점검 관리 방법 보기

1. 점검 체계 개요

Gatrix는 3단계 점검 체계를 제공합니다. 각 단계별로 점검 범위가 다르며, 상황에 맞게 적절한 점검 방식을 선택해야 합니다.

flowchart TB
    subgraph 서비스["🌐 서비스 전체 점검"]
        A[모든 유저 접속 차단<br/>최상위 우선순위]
    end

    subgraph 클라이언트["📱 클라이언트 버전별 점검"]
        B[특정 버전만 차단<br/>API 조회 방식]
    end

    subgraph 월드["🗺️ 월드별 점검"]
        C[특정 월드만 점검<br/>다른 월드는 정상 운영]
    end

    A --> B
    B --> C

    style A fill:#ffcdd2
    style B fill:#fff9c4
    style C fill:#e3f2fd

점검 적용 우선순위

flowchart TD
    A[유저 접속 시도] --> B{서비스 전체<br/>점검 중?}
    B -->|예| C[❌ 접속 차단<br/>점검 안내]
    B -->|아니오| D{해당 클라이언트<br/>버전 점검 중?}
    D -->|예| E[❌ 접속 차단<br/>버전별 점검 안내]
    D -->|아니오| F{접속할 월드<br/>점검 중?}
    F -->|예| G[❌ 해당 월드만<br/>접속 불가]
    F -->|아니오| H[✅ 정상 접속]

    style C fill:#ffcdd2
    style E fill:#ffcdd2
    style G fill:#fff9c4
    style H fill:#c8e6c9

2. 서비스 전체 점검 (Service Maintenance)

모든 유저의 접속을 차단하는 최상위 점검입니다. 서버 업데이트, DB 마이그레이션 등 전체 서비스에 영향을 주는 작업 시 사용합니다.

경로: 관리자 패널 → 서비스 제어 → 서비스 점검
필요 권한: maintenance.manage

화면 구성

서비스 점검 설정 화면

설정 항목

항목 설명
점검 상태 현재 점검 활성화 여부
시작 시간 점검 시작 일시 (비워두면 즉시 시작)
종료 시간 점검 종료 일시 (비워두면 수동 종료)
기존 플레이어 강제 종료 점검 시작 시 접속 중인 유저 강제 퇴장
점검 메시지 유저에게 표시할 안내 메시지
다국어 메시지 언어별로 다른 메시지 설정 가능

서비스 점검의 특징

flowchart LR
    A[서비스 점검 시작] --> B[모든 유저 접속 차단]
    B --> C[실시간 적용]
    C --> D[화이트리스트만<br/>접속 가능]

    style A fill:#ffcdd2
    style D fill:#c8e6c9

⚠️ 기존 플레이어 동작

점검이 시작되어도 이미 접속 중인 플레이어는 즉시 차단되지 않습니다.

설정 동작
강제 종료: OFF 기존 플레이어는 계속 플레이 가능. 단, 게임 화면 우측 상단에 점검 중임을 알리는 작은 배너가 표시됩니다.
강제 종료: ON 점검 시작 시 접속 중인 모든 유저를 강제 퇴장시킵니다. 설정에 따라 즉시 또는 일정 시간(예: 5분) 후 킥됩니다. 킥 전 게임 내에서 안내 메시지가 표시됩니다.

💡 게임 내 점검 배너: 점검 중에도 플레이할 수 있는 유저들에게는 화면 우측 상단 아래에 "점검 중" 배너가 나타나, 서비스 상태를 인지할 수 있도록 안내합니다. 점검 종료 후 배너는 자동으로 사라집니다.

3. 클라이언트 버전별 점검 (Version Maintenance)

특정 클라이언트 버전만 점검 상태로 전환합니다. API 조회 방식으로 동작하며, 클라이언트가 버전 체크 API를 호출할 때 점검 상태를 반환합니다.

경로: 관리자 패널 → 클라이언트 버전 → 버전 편집
필요 권한: client-versions.manage

🎬 영상 가이드: 클라이언트 버전 관리 보기

설정 방법

  1. 클라이언트 버전 목록에서 해당 버전의 [편집] 클릭
  2. 상태 라벨을 점검 중 (Maintenance)으로 변경
  3. 점검 메시지 입력
  4. [저장]

API 조회 방식의 특징

sequenceDiagram
    participant C as 게임 클라이언트
    participant E as Edge API
    participant G as Gatrix

    C->>E: 버전 체크 요청 (v2.1.0)
    E->>G: 버전 상태 조회
    G-->>E: 상태: MAINTENANCE
    E-->>C: 점검 중 응답 + 메시지
    C->>C: 점검 안내 화면 표시

주요 특징:
- 클라이언트가 버전 체크 API를 호출할 때 점검 상태를 확인합니다.
- 이미 접속 중인 유저에게는 즉시 반영되지 않습니다.
- 신규 접속자 또는 재접속 시에만 점검이 적용됩니다.

활용 시나리오

상황 설명
구버전 점검 강제 업데이트 전 구버전 유저 차단
신버전 테스트 신버전을 점검 상태로 두고 화이트리스트로 테스트
롤백 대비 문제 발생 시 특정 버전만 빠르게 차단

4. 월드별 점검 (World Maintenance)

특정 게임 월드(서버)만 점검 상태로 전환합니다. 다른 월드는 정상 운영됩니다.

경로: 관리자 패널 → 게임 월드 → 월드 편집
필요 권한: game-worlds.manage

🎬 영상 가이드: 게임 월드 관리 보기

설정 방법

  1. 게임 월드 목록에서 해당 월드의 [편집] 클릭
  2. 점검 중 토글을 활성화
  3. 점검 일정 설정 (선택사항)
  4. [저장]

월드별 점검 흐름

flowchart TD
    subgraph 서버목록["서버 선택 화면"]
        A["🟢 월드A (정상)"]
        B["🔴 월드B (점검 중)"]
        C["🟢 월드C (정상)"]
    end

    A --> D[접속 가능]
    B --> E[접속 차단<br/>점검 안내]
    C --> D

    style B fill:#ffcdd2
    style D fill:#c8e6c9
    style E fill:#ffcdd2

활용 시나리오

상황 설명
월드별 업데이트 특정 월드만 데이터 마이그레이션
부하 분산 과부하 월드 임시 점검
이벤트 준비 이벤트 월드 사전 세팅

5. 실시간 점검 vs API 조회 점검

Gatrix의 점검은 적용 방식에 따라 두 가지로 나뉩니다.

비교표

구분 실시간 적용 API 조회 적용
서비스 전체 점검 ✅
클라이언트 버전 점검 ✅
월드별 점검 ✅
기존 접속자 즉시 적용 재접속 시 적용
적용 시점 설정 즉시 API 호출 시

실시간 적용 점검

flowchart LR
    A[점검 설정 저장] --> B[서버에서<br/>접속 확인]
    B --> C[즉시 차단/<br/>허용 결정]

    style C fill:#c8e6c9

API 조회 적용 점검

flowchart LR
    A[클라이언트 실행] --> B[버전 체크<br/>API 호출]
    B --> C[점검 상태<br/>응답 받음]
    C --> D[점검 화면<br/>표시]

    style D fill:#fff9c4

6. 화이트리스트 (Whitelist)

점검 중에도 QA팀, 개발팀, 마켓 검수팀이 접속할 수 있도록 예외를 설정합니다.

경로: 관리자 패널 → 화이트리스트
필요 권한: whitelist.manage

🎬 영상 가이드: 화이트리스트 관리 보기

화면 구성

화이트리스트 관리 화면

지원하는 화이트리스트 유형

유형 설명 사용 사례
계정 ID (Account ID) 특정 유저 계정만 허용 QA 테스터 개인 계정, 마켓 검수 계정
IP 주소 특정 IP에서의 접속 허용 사내 네트워크, 개발실 IP

⚠️ 참고: Device ID는 화이트리스트 조건으로 사용하지 않습니다. 계정 ID와 IP 주소만 체크합니다.

화이트리스트 동작 흐름

flowchart TD
    A[접속 시도] --> B{점검 중?}
    B -->|아니오| C[✅ 접속 허용]
    B -->|예| D{계정 ID<br/>화이트리스트?}
    D -->|예| C
    D -->|아니오| E{IP 주소<br/>화이트리스트?}
    E -->|예| C
    E -->|아니오| F[❌ 접속 차단]

    style C fill:#c8e6c9
    style F fill:#ffcdd2

등록 가이드

대상 추천 유형 이유
애플/구글 검수팀 계정 ID 검수팀 IP 알 수 없음
사내 전체 IP 주소 일괄 허용 편리
재택 근무자 계정 ID IP 변경 가능성
외부 QA 업체 계정 ID 보안상 계정 단위 관리

7. 점검 종류별 설정 가이드

정기 점검 (전체 서비스)

정기 점검 및 긴급 점검 프로세스

점검 프로세스 흐름도

버전별 강제 업데이트

flowchart TD
    A[신버전 배포] --> B[구버전 상태를<br/>'점검 중'으로 변경]
    B --> C[구버전 유저:<br/>업데이트 안내]
    C --> D[신버전으로<br/>업데이트]

    style D fill:#c8e6c9

8. 점검 설정 체크리스트

✅ 정기 점검

D-1일 (전일)
- [ ] 서비스 점검 예약 설정
- [ ] 시작/종료 시간 정확히 입력
- [ ] 사전 공지사항 게시
- [ ] QA/검수 계정 화이트리스트 등록

D-Day
- [ ] 30분 전 인게임 알림 발송
- [ ] 점검 시작 확인
- [ ] QA 테스트 완료
- [ ] 점검 종료 및 서버 오픈 확인
- [ ] 점검 완료 공지사항 게시

✅ 긴급 점검

9. 자주 묻는 질문 (FAQ)

Q: 버전별 점검을 설정했는데 기존 유저가 계속 플레이하고 있어요.

A: 클라이언트 버전별 점검은 API 조회 방식입니다. 이미 접속 중인 유저에게는 적용되지 않으며, 재접속 시에만 점검 상태가 반영됩니다.

Q: 화이트리스트에 Device ID를 등록할 수 있나요?

A: 아니요, 현재 화이트리스트는 계정 ID와 IP 주소만 지원합니다. Device ID는 사용하지 않습니다.

Q: 서비스 점검 중에 월드별 점검을 따로 설정해야 하나요?

A: 아니요, 서비스 전체 점검이 최상위 우선순위이므로 모든 월드가 자동으로 차단됩니다.

Q: 점검 시간을 연장하려면?

A: 서비스 점검 화면에서 종료 시간을 수정하고 저장하면 됩니다. 연장 시 최소 30분 전에 공지를 갱신하세요.

10. 트러블슈팅 케이스

🔴 케이스 1: 점검을 걸었는데 유저가 계속 접속해요

증상: 서비스 점검을 시작했는데 일부 유저가 여전히 게임 중

원인 및 해결:

원인 해결 방법
"기존 플레이어 강제 종료" 비활성화 해당 옵션 활성화 후 재저장
화이트리스트에 등록된 계정/IP 화이트리스트 목록 확인
잘못된 환경에서 점검 설정 환경 선택기 확인 (Production인지)
클라이언트 버전 점검만 설정 서비스 전체 점검으로 변경

🔴 케이스 2: 점검 종료 버튼을 눌렀는데 서버가 안 열려요

증상: 점검 종료를 했는데 유저가 여전히 접속 불가

원인 및 해결:

원인 해결 방법
월드별 점검이 별도로 남아있음 게임 월드에서 점검 해제
클라이언트 버전 상태가 점검 중 클라이언트 버전 상태 확인
게임 서버 자체가 미기동 인프라팀에 서버 상태 확인 요청
캐시/CDN 문제 5분 대기 후 재확인

🔴 케이스 3: 화이트리스트 등록했는데 QA팀이 접속 못해요

증상: 화이트리스트에 등록한 계정/IP인데 점검 안내가 표시됨

원인 및 해결:

원인 해결 방법
계정 ID 오타 UUID 정확히 복사했는지 확인
IP 주소 변경 VPN 사용 시 IP 변경 가능, 계정 ID로 등록
환경 불일치 올바른 환경에 화이트리스트 등록했는지 확인
클라이언트 캐싱 앱 강제 종료 후 재시작

🔴 케이스 4: 점검 예약을 했는데 시간이 되어도 안 걸려요

증상: 점검 시작 시간을 설정했는데 자동으로 시작되지 않음

원인 및 해결:

원인 해결 방법
시간대(Timezone) 불일치 UTC vs KST 확인
과거 시간 입력 현재 시간 이후로 재설정
저장 안 함 [저장] 버튼 눌렀는지 확인
백엔드 서버 문제 담당 개발팀 확인 요청

🔴 케이스 5: 점검 메시지가 이상하게 표시돼요

증상: 점검 안내 메시지에 HTML 태그가 그대로 보이거나 깨짐

원인 및 해결:

원인 해결 방법
HTML 태그 사용 점검 메시지는 Plain Text만 지원, 태그 제거
특수문자 문제 <, >, & 등 특수문자 확인
인코딩 문제 복사/붙여넣기 대신 직접 입력

11. 동영상 가이드

점검 관리 전체 흐름

🎬
동영상 보기: 06-maintenance

클릭하여 새 창에서 재생하세요.

화이트리스트 관리

🎬
동영상 보기: 08-whitelists

클릭하여 새 창에서 재생하세요.

이전 장: ← 제 5장: 게임 월드 관리
다음 장: 제 7장: 공지사항 관리 →

제 7장: 공지사항 관리 (Service Notices)

게임 내 공지사항은 유저와의 가장 기본적인 소통 창구입니다. 점검 안내, 이벤트 홍보, 버그 수정 내역 등을 알릴 때 사용합니다.

경로: 게임 관리 (Game) → 서비스 공지 (Service Notices)
필요 권한: service-notices.manage

🎬 영상 가이드: 공지사항 관리 방법 보기

1. 화면 구성

공지사항 관리 페이지의 전체 화면입니다.

공지사항 노출 로직

flowchart LR
    A[클라이언트 접속] --> B{점검 중인가?}
    B -->|Yes| C[점검 공지 우선 노출]
    B -->|No| D{활성 공지 있음?}
    D -->|Yes| E[공지사항 노출]
    D -->|No| F[공지 없음]

상단 툴바 버튼 설명

버튼 설명
미리보기 게임 내 웹뷰에서 공지사항이 어떻게 보이는지 미리 확인합니다.
공지 추가 새로운 공지사항을 작성합니다.

테이블 컬럼 설명

컬럼 설명
제목 공지사항 제목
📌 (상단 고정) 상단 고정 여부
현재 표시 현재 유저에게 노출 중인지 여부
상태 활성(Active) / 비활성(Inactive)
카테고리 점검, 이벤트, 공지, 프로모션, 기타
적용 대상 대상 플랫폼 및 채널
적용 기간 노출 시작~종료 일시
생성일 공지 작성 일시
수정일 최근 수정 일시
작업 ✏️ 편집, 🗑️ 삭제 버튼

2. 공지사항 작성하기

[공지 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.

공지사항 추가 폼

입력 항목 상세 설명

섹션 항목 필수 설명
기본 설정 사용 여부 ✅ 토글 스위치로 활성화/비활성화 설정
대상 지정 대상 플랫폼 전체 또는 특정 플랫폼(iOS, Android, PC 등) 선택
대상 채널 특정 서비스 채널 선택
노출 기간 시작일시 비워두면 즉시 게시
종료일시 비워두면 영구 게시
표시 옵션 상단 고정 중요 공지를 목록 최상단에 고정
분류 카테고리 ✅ 점검/이벤트/공지/프로모션/기타
태그 분류용 태그
내용 제목 ✅ 유저에게 표시되는 제목
내용 ✅ Rich Text Editor로 HTML 형식 작성

카테고리 종류

카테고리 용도 예시
점검 (Maintenance) 점검 관련 안내 "1/15 정기점검 안내"
이벤트 (Event) 게임 이벤트 홍보 "설날 이벤트 안내"
공지 (Notice) 일반 공지사항 "이용약관 변경 안내"
프로모션 (Promotion) 상품/결제 관련 "신규 패키지 출시 안내"
기타 (Other) 그 외 안내 "커뮤니티 가이드라인"

3. 다국어 공지 작성 (Multi-language Support)

Gatrix는 글로벌 서비스를 위해 다국어 공지 입력을 지원합니다.
특히 중국 서비스를 고려하여 간체/번체 입력을 올바르게 구분해야 합니다.

언어 코드 입력 예시 (제목)
한국어 ko-KR 정기 점검 안내
영어 en-US Scheduled Maintenance
중국어(간체) zh-CN 定期维护通知 (중국 본토)
중국어(번체) zh-TW 定期維護通知 (대만/홍콩)

🌏 유의사항:
- 중국 서비스를 준비 중이라면 반드시 중국어(간체) 내용을 포함하세요.
- 번역된 내용이 없으면 기본 언어(한국어 또는 영어)로 표시될 수 있습니다.

공지사항 내용은 Rich Text Editor를 통해 HTML 형식으로 작성할 수 있습니다.

에디터 기능

기능 설명
폰트 설정 폰트 종류 선택 (Noto Sans 등)
크기 조절 텍스트 크기 조절
텍스트 스타일 굵게(B), 기울임(I), 밑줄(U)
색상 설정 글자색, 배경색 변경
정렬 왼쪽, 가운데, 오른쪽 정렬
목록 번호 목록, 글머리 기호 목록
이미지 삽입 이미지 URL 또는 업로드
동영상 삽입 YouTube 등 동영상 임베드
링크 삽입 외부 링크 추가
이모지 이모지 삽입

💡 팁: 모바일 화면에서의 가독성을 위해 복잡한 레이아웃은 피하고, 간결하게 작성하세요.

5. 노출 관리 (Visibility)

공지사항의 노출 상태는 여러 조건에 따라 결정됩니다.

flowchart TD
    A[공지사항] --> B{사용 여부?}
    B -->|비활성화| C[❌ 노출 안됨]
    B -->|활성화| D{현재 시간?}
    D -->|시작 전| E[⏳ 예약됨]
    D -->|기간 내| F[✅ 현재 노출 중]
    D -->|종료 후| G[⏹️ 종료됨]

    style C fill:#ffcdd2
    style E fill:#fff9c4
    style F fill:#c8e6c9
    style G fill:#e0e0e0

노출 상태 아이콘

상태 아이콘 조건
현재 노출 중 🟢 Active + 현재 시간이 기간 내
예약됨 🟡 Active + 시작 시간이 미래
종료됨 ⚪ 종료 시간이 지남
비활성 ⚫ 사용 여부 비활성화

6. 미리보기 및 공유

웹뷰 미리보기 (Preview)

작성된 공지사항이 실제 게임 내 웹뷰에서 어떻게 보일지 미리 확인할 수 있습니다.

  1. 목록 상단의 [미리보기] 버튼 클릭
  2. 새 창에서 실제 게임에 적용되는 웹뷰 화면 확인

URL 복사 (Copy URL)

공지사항의 직접 링크가 필요할 때 사용합니다. (예: 커뮤니티에 링크 공유)

7. 운영 시나리오

시나리오: 점검 공지 작성

flowchart LR
    A[D-1일] --> B[점검 공지 작성]
    B --> C[시작일시: 즉시<br/>종료일시: 점검 종료 후]
    C --> D[상단 고정 활성화]
    D --> E[게시]

    style A fill:#e3f2fd
    style E fill:#c8e6c9
  1. [공지 추가] 클릭
  2. 카테고리: 점검 선택
  3. 제목: "1/15(수) 정기점검 안내 (10:00~12:00)"
  4. 상단 고정: 활성화
  5. 내용 작성 후 [저장]

시나리오: 이벤트 공지 예약

flowchart LR
    A[이벤트 기획] --> B[공지 작성]
    B --> C[시작일시: 이벤트 시작일<br/>종료일시: 이벤트 종료일]
    C --> D[예약 상태로 대기]
    D --> E[자동 게시]

    style D fill:#fff9c4
    style E fill:#c8e6c9
  1. [공지 추가] 클릭
  2. 카테고리: 이벤트 선택
  3. 시작일시: 이벤트 시작일 설정
  4. 종료일시: 이벤트 종료일 설정
  5. 내용 작성 후 [저장] → 자동으로 예약됨

8. 공지사항 관리 체크리스트

점검 공지 체크리스트

이벤트 공지 체크리스트

9. 자주 묻는 질문 (FAQ)

Q: 공지사항을 올렸는데 게임에서 안 보여요.

A: 다음을 순서대로 확인하세요.
1. 사용 여부가 활성화되어 있나요?
2. 현재 시간이 게시 기간(시작일시 ~ 종료일시) 사이인가요?
3. 플랫폼 설정이 올바른가요? (예: iOS로 접속했는데 타겟이 Android만 설정된 경우)
4. 환경(Environment) 선택이 올바른가요?

Q: HTML 태그를 쓸 수 있나요?

A: 네, 내용은 웹뷰를 통해 렌더링되므로 HTML 태그 사용이 가능합니다. Rich Text Editor에서 자동으로 HTML 코드가 생성됩니다.

Q: 이미지를 넣으려면 어떻게 하나요?

A: Rich Text Editor의 이미지 아이콘을 클릭하여 이미지 URL을 입력하거나 직접 업로드할 수 있습니다.

10. 트러블슈팅 케이스

🔴 케이스 1: 공지사항을 등록했는데 게임에서 안 보여요

증상: 대시보드에서는 등록된 공지가 게임 내에서 표시되지 않음

원인 및 해결:

원인 해결 방법
사용 여부 비활성화 "사용" 토글 상태 확인
기간 설정 오류 시작일시가 미래이거나 종료일시가 과거
플랫폼/채널 불일치 대상 설정이 해당 유저에게 적용되는지 확인
환경 불일치 Production 환경에 등록했는지 확인

🔴 케이스 2: 이미지가 깨져서 보여요

증상: 공지 내 이미지가 X 표시이거나 로딩 안됨

원인 및 해결:

원인 해결 방법
이미지 URL 오류 URL을 브라우저에서 직접 열어 확인
HTTP/HTTPS 혼용 HTTPS URL 사용 권장
CDN 접근 제한 이미지 호스팅 서비스 접근성 확인
이미지 삭제됨 원본 이미지 존재 여부 확인

🔴 케이스 3: 한국어는 보이는데 영어 공지가 비어있어요

증상: 다국어 공지에서 특정 언어만 표시됨

원인 및 해결:

원인 해결 방법
해당 언어 미입력 언어별 내용 모두 입력 확인
빈 문자열 저장 공백만 있는 경우도 비어 보임
기본 언어 Fallback 기본 언어(한국어)만 입력 시 다른 언어에도 표시됨 확인

💡 단일 국가 서비스 시: 다국어 메시지 입력은 필요하지 않습니다. 기본 메시지만 입력하세요.

11. 동영상 가이드

공지사항 관리 전체 흐름

🎬
동영상 보기: 09-servicenotices

클릭하여 새 창에서 재생하세요.

이전 장: ← 제 6장: 점검 관리
다음 장: 제 8장: 인게임 팝업 관리 →

제 8장: 인게임 팝업 관리 (Ingame Popup Notices)

게임 접속 시 또는 특정 조건에서 자동으로 표시되는 팝업 공지입니다. 긴급 안내, 이벤트 홍보, 중요 정보 전달 등에 활용됩니다.

경로: 게임 관리 (Game) → 인게임 팝업 공지 (Ingame Popup Notices)
필요 권한: popup-notices.manage

🎬 영상 가이드: 인게임 팝업 관리 방법 보기

1. 화면 구성

인게임 팝업 관리 페이지의 전체 화면입니다.

인게임 팝업 목록 화면

상단 툴바 버튼 설명

버튼 설명
팝업 공지 추가 새로운 팝업 공지를 작성합니다.
SDK 연동 가이드 클라이언트에서 팝업 공지를 조회하는 API 문서를 제공합니다.

테이블 컬럼 설명

컬럼 설명
내용 팝업에 표시되는 메시지 내용 (미리보기)
현재 표시 현재 유저에게 노출 중인지 여부
상태 활성(Active) / 비활성(Inactive)
우선순위 노출 순서 (숫자가 작을수록 먼저 표시)
대상 설정 대상 플랫폼 및 채널
적용 기간 노출 시작~종료 일시
생성일 팝업 생성 일시
작업 ✏️ 편집, 🗑️ 삭제 버튼

2. 팝업 공지 작성하기

[팝업 공지 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.

팝업 공지 추가 폼

입력 항목 상세 설명

섹션 항목 필수 설명
기본 설정 사용 여부 ✅ 토글 스위치로 활성화/비활성화 설정
대상 지정 대상 플랫폼 전체 또는 특정 플랫폼 선택
대상 채널 특정 서비스 채널 선택
노출 기간 시작일시 비워두면 즉시 표시
종료일시 비워두면 영구 표시
노출 설정 우선순위 숫자가 작을수록 먼저 표시 (기본: 100)
한번만 노출 유저당 1회만 표시 (로그인/접속 시마다 표시하지 않음)
템플릿 사용 메시지 템플릿에서 내용 불러오기
내용 내용 ✅ Plain Text 형식으로 팝업 메시지 입력
설명 관리용 메모 (유저에게 표시되지 않음)

3. 팝업 vs 서비스 공지 비교

어떤 공지 방식을 사용해야 할지 헷갈린다면 아래 표를 참고하세요.

구분 인게임 팝업 서비스 공지
표시 방식 게임 내 팝업창 자동 표시 공지사항 메뉴 클릭 시 표시
노출 시점 게임 접속/로그인 시 자동 유저가 직접 확인
내용 형식 Plain Text (간결하게) Rich HTML (상세하게)
적합한 용도 긴급 안내, 짧은 공지 상세한 이벤트 안내, 점검 상세
한번만 노출 지원 ✅ 미지원 
flowchart TD
    A[공지할 내용] --> B{긴급도?}
    B -->|높음: 즉시 알려야 함| C[인게임 팝업]
    B -->|보통: 확인할 때 보면 됨| D[서비스 공지]

    C --> E{내용 길이?}
    E -->|짧음: 1-2문장| F[팝업만 사용]
    E -->|길음: 상세 설명 필요| G[팝업 + 공지 둘 다]

    style C fill:#ffcdd2
    style D fill:#e3f2fd

4. 우선순위 설정

여러 팝업이 동시에 활성화된 경우, 우선순위에 따라 표시 순서가 결정됩니다.

우선순위 표시 순서 권장 용도
1-10 먼저 표시 긴급 공지, 치명적 버그 안내
50-100 중간 일반 이벤트, 업데이트 안내
100-200 나중 표시 덜 중요한 안내, 광고

💡 팁: 우선순위는 "숫자가 작을수록 먼저 표시"됩니다. 긴급 공지는 우선순위 1-10을 사용하세요.

팝업 노출 우선순위

flowchart TD
    A[로그인 성공] --> B[활성 팝업 목록 조회]
    B --> C[우선순위 정렬 (내림차순)]
    C --> D[1순위 팝업 노출]
    D --> E{닫기 버튼 클릭}
    E --> F[오늘 하루 보지 않기 체크?]
    F -->|Yes| G[24시간 동안 노출 안 함]
    F -->|No| H[다음 접속 시 다시 노출]
    E --> I[다음 순위 팝업 노출]

적합한 활용:
- 신규 기능 안내 (한 번만 알려주면 됨)
- 이벤트 시작 알림 (반복 알림 불필요)
- 약관 변경 고지 (동의 후 재표시 불필요)

6. 운영 시나리오

시나리오: 긴급 서버 이슈 알림

flowchart LR
    A[서버 이슈 발생] --> B[즉시 팝업 생성]
    B --> C[우선순위: 1]
    C --> D[한번만 노출: 끔]
    D --> E[게시]

    style A fill:#ffcdd2
    style E fill:#c8e6c9
  1. [팝업 공지 추가] 클릭
  2. 내용: "현재 일부 서버에서 접속 지연 현상이 발생하고 있습니다. 빠른 시일 내 복구하겠습니다."
  3. 우선순위: 1 (최우선)
  4. 한번만 노출: 끔 (접속할 때마다 표시)
  5. [저장]

시나리오: 이벤트 시작 안내

  1. [팝업 공지 추가] 클릭
  2. 내용: "🎉 설날 이벤트가 시작되었습니다! 자세한 내용은 공지사항을 확인해 주세요."
  3. 시작일시: 이벤트 시작일
  4. 종료일시: 이벤트 종료일
  5. 한번만 노출: 켬 (한 번만 알림)
  6. [저장]

7. 자주 묻는 질문 (FAQ)

Q: 팝업이 너무 많으면 어떻게 되나요?

A: 우선순위에 따라 순차적으로 표시됩니다. 유저가 첫 번째 팝업을 닫으면 두 번째 팝업이 나타납니다. 너무 많은 팝업은 유저 경험에 좋지 않으니 5개 이내로 유지하세요.

Q: "한번만 노출"을 설정했는데 유저가 다시 보고 싶어합니다.

A: "한번만 노출"은 유저 기기에 쿠키/로컬 스토리지로 기록됩니다. 유저가 앱을 재설치하거나 브라우저 데이터를 삭제하면 다시 표시됩니다.

Q: 팝업에 이미지를 넣을 수 있나요?

A: 현재 인게임 팝업은 Plain Text만 지원합니다. 이미지가 필요하면 서비스 공지(Rich HTML)를 활용하고, 팝업에서는 "자세한 내용은 공지사항을 확인해 주세요"라고 안내하세요.

8. 트러블슈팅 케이스

🔴 케이스 1: 팝업이 여러 번 표시돼요

증상: "한번만 노출"을 설정했는데 유저에게 반복적으로 표시됨

원인 및 해결:

원인 해결 방법
앱 재설치 정상 동작 - 재설치 시 기록 초기화
다른 기기 접속 정상 동작 - 기기별 기록
팝업 ID 변경 팝업 수정 시 ID 유지 확인

🔴 케이스 2: 팝업이 전혀 표시되지 않아요

증상: 활성화한 팝업이 게임 접속 시 표시되지 않음

원인 및 해결:

원인 해결 방법
사용 여부 비활성화 토글 상태 확인
기간 설정 오류 시작/종료 일시 확인
플랫폼 대상 불일치 유저 플랫폼에 맞는 대상 설정 확인
이미 본 것으로 기록됨 "한번만 노출"이 켜져 있고 이미 확인한 경우

9. 동영상 가이드

인게임 팝업 관리 전체 흐름

🎬
동영상 보기: 10-ingamepopups

클릭하여 새 창에서 재생하세요.

이전 장: ← 제 7장: 공지사항 관리
다음 장: 제 9장: 쿠폰 관리 →

제 9장: 쿠폰 관리 (Coupon Management)

쿠폰은 마케팅, 보상, 프로모션에 필수적인 기능입니다. 이벤트 보상, 사전 예약 혜택, 협찬 코드 등 다양한 용도로 활용됩니다.

경로: 게임 관리 (Game) → 쿠폰 → 쿠폰 정의 (Coupon Definitions)
필요 권한: coupons.manage

1. 화면 구성

쿠폰 관리 페이지의 전체 화면입니다.

쿠폰 목록 화면

상단 툴바 버튼 설명

버튼 설명
쿠폰 생성 새로운 쿠폰을 정의합니다.
SDK 연동 가이드 클라이언트에서 쿠폰을 사용하는 API 문서를 제공합니다.

테이블 컬럼 설명

컬럼 설명
이름 쿠폰 이름 (관리용)
쿠폰 코드 실제 사용되는 쿠폰 코드 또는 코드 패턴
유형 NORMAL(일반) / UNIQUE(고유)
참여 보상 쿠폰 사용 시 지급되는 보상
사용률 사용된 코드 수 / 전체 발행 수
시작 쿠폰 유효 시작일
종료 쿠폰 유효 종료일
생성일 / 상태 생성 일시 및 현재 상태
작업 코드 확인, ✏️ 편집, 🗑️ 삭제 버튼

2. 쿠폰 생성하기

[쿠폰 생성] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.

쿠폰 생성 폼

입력 항목 상세 설명

섹션 항목 필수 설명
기본 설정 사용중 ✅ 쿠폰 활성화 여부
기본 정보 이름 ✅ 쿠폰 이름 (관리용)
설명 쿠폰에 대한 부가 설명
대상 지정 대상 플랫폼 사용 가능한 플랫폼 제한
대상 채널 사용 가능한 채널 제한
코드 및 수량 유형 ✅ NORMAL(공용) / UNIQUE(개별 생성)
코드 패턴 코드 생성 패턴 (영문+숫자 등)
발행 수량 생성할 쿠폰 코드 개수
사용 제한 유저별 사용 횟수 한 유저가 사용할 수 있는 최대 횟수
사용 가능 기간 쿠폰 유효 기간 (시작~종료)

3. 쿠폰 유형 이해

NORMAL (공용 쿠폰)

모든 유저가 동일한 코드를 사용합니다.

쿠폰 보상 프로세스

flowchart LR
    A[유저: 쿠폰 입력] --> B[게임 서버]
    B --> C[Gatrix: 코드 검증]
    C --> B
    B --> D[우편함으로 보상 지급]

    style C fill:#fff9c4

특징:
- 한 개의 코드로 여러 유저가 사용
- SNS, 커뮤니티에 코드 공개 시 적합
- 총 발행 수량 = 전체 사용 가능 횟수

예시: 이벤트 프로모션 코드 SUMMER2024

UNIQUE (개별 쿠폰)

유저마다 고유한 코드가 생성됩니다.

flowchart LR
    A[유저 A] --> B[코드: ABC1-2345]
    C[유저 B] --> D[코드: DEF6-7890]
    E[유저 C] --> F[코드: GHI0-1234]

    style B fill:#c8e6c9
    style D fill:#c8e6c9
    style F fill:#c8e6c9

특징:
- 유저마다 다른 코드 발급
- 코드 유출 방지
- 개인별 추적 가능

예시: 사전 예약 보상, VIP 전용 쿠폰

4. 쿠폰 발행 플로우

flowchart TD
    subgraph 관리자["👨‍💼 관리자 (Gatrix)"]
        A[쿠폰 정의 생성] --> B{유형 선택}
        B -->|NORMAL| C[공용 코드 1개 생성]
        B -->|UNIQUE| D[개별 코드 N개 생성]
    end

    subgraph 배포["📤 코드 배포"]
        C --> E[SNS/커뮤니티 공개]
        D --> F[이메일/DM 개별 발송]
    end

    subgraph 사용자["🎮 유저"]
        E --> G[코드 입력]
        F --> G
        G --> H[보상 수령]
    end

    style A fill:#e3f2fd
    style H fill:#c8e6c9

5. 보상 설정

쿠폰 사용 시 지급될 보상을 설정합니다.

보상 템플릿 사용

미리 정의된 보상 템플릿을 선택하여 간편하게 설정할 수 있습니다.

직접 설정

JSON 형식으로 보상 내용을 직접 입력합니다.

{
  "items": [
    { "itemId": "gold", "quantity": 1000 },
    { "itemId": "gem", "quantity": 50 }
  ]
}

6. 운영 시나리오

시나리오: 사전 예약 쿠폰 발급

flowchart LR
    A[사전 예약 명단<br/>10,000명] --> B[UNIQUE 쿠폰 생성<br/>10,000개]
    B --> C[코드 다운로드<br/>CSV 파일]
    C --> D[이메일 발송<br/>개별 코드 전달]

    style B fill:#e3f2fd
    style D fill:#c8e6c9
  1. [쿠폰 생성] 클릭
  2. 유형: UNIQUE 선택
  3. 발행 수량: 10,000
  4. 보상 설정
  5. [저장] → 코드 자동 생성
  6. [코드 다운로드] → CSV 파일로 내보내기
  7. 사전 예약 명단과 매칭하여 이메일 발송

시나리오: 미디어/인플루언서 공용 코드

flowchart LR
    A[프로모션 기획] --> B[NORMAL 쿠폰 생성<br/>코드: YOUTUBE2024]
    B --> C[사용 제한: 10,000회]
    C --> D[유튜버에게 코드 전달]
    D --> E[영상으로 공개]

    style B fill:#e3f2fd
    style E fill:#c8e6c9
  1. [쿠폰 생성] 클릭
  2. 유형: NORMAL 선택
  3. 코드: YOUTUBE2024 (직접 지정)
  4. 발행 수량: 10,000 (최대 사용 횟수)
  5. 유저별 사용 횟수: 1 (중복 사용 방지)
  6. [저장]

7. 쿠폰 관리 체크리스트

쿠폰 생성 전 체크리스트

쿠폰 발급 후 체크리스트

8. 자주 묻는 질문 (FAQ)

Q: 쿠폰 코드를 직접 지정할 수 있나요?

A: NORMAL 쿠폰의 경우 코드를 직접 지정할 수 있습니다. UNIQUE 쿠폰은 패턴에 따라 자동 생성됩니다.

Q: 발급된 쿠폰 코드를 확인하려면?

A: 쿠폰 목록에서 해당 쿠폰의 [발행된 코드 수]를 클릭하면 발급된 코드 목록을 확인할 수 있습니다. CSV로 다운로드도 가능합니다.

Q: 쿠폰 사용 내역을 추적할 수 있나요?

A: 네, 감사 로그(Audit Log)에서 쿠폰 사용 내역을 확인할 수 있습니다. 또한 쿠폰별 사용률도 목록에서 바로 확인 가능합니다.

Q: 이미 발급된 쿠폰을 비활성화하면?

A: 쿠폰을 비활성화하면 더 이상 새로운 사용이 불가능합니다. 이미 사용된 보상은 회수되지 않습니다.

이전 장: ← 제 9장: 인게임 팝업 관리
다음 장: 제 11장: 설문조사 관리 →

제 10장: 설문조사 관리 (Surveys)

게임 내 설문조사를 만들어 유저 의견을 수집하고 분석할 수 있습니다. 설문 참여 보상을 통해 참여율을 높일 수 있습니다.

경로: 게임 관리 (Game) → 설문지 (Surveys)
필요 권한: surveys.manage

1. 화면 구성

설문조사 관리 페이지의 전체 화면입니다.

설문조사 목록 화면

상단 툴바 버튼 설명

버튼 설명
설문 추가 새로운 설문조사를 생성합니다.

테이블 컬럼 설명

컬럼 설명
설문 ID 플랫폼별 설문 고유 식별자
제목 설문조사 제목
발동 조건 설문이 표시되는 조건
보상 설문 참여 시 지급되는 보상
상태 활성(Active) / 비활성(Inactive)
생성일 설문 생성 일시
작업 ✏️ 편집, 🗑️ 삭제 버튼

2. 설문조사 생성

기본 정보

항목 필수 설명
설문 ID ✅ 플랫폼별 고유 식별자
제목 ✅ 설문조사 제목
설명 설문에 대한 부가 설명
상태 활성화 여부

발동 조건

설문이 유저에게 표시되는 조건을 설정합니다.

조건 설명
즉시 표시 조건 없이 바로 표시
특정 레벨 도달 게임 내 특정 레벨 이상
플레이 시간 일정 플레이 시간 경과 후
스테이지 클리어 특정 스테이지 완료 후

3. 설문 참여 보상

유저 참여를 유도하기 위해 보상을 설정할 수 있습니다.

flowchart LR
    A[설문 완료] --> B[보상 지급]
    B --> C[아이템/재화 수령]

    style B fill:#c8e6c9

보상 설정

보상 종류 예시
게임 재화 골드 1,000, 젬 50
아이템 가챠 티켓 1장
쿠폰 설문 참여 감사 쿠폰

4. 설문 결과 분석

수집된 설문 결과를 분석하여 게임 개선에 활용합니다.

결과 확인

  1. 설문 목록에서 해당 설문 선택
  2. 결과 보기 클릭
  3. 통계 및 개별 응답 확인

5. 자주 묻는 질문 (FAQ)

Q: 설문을 특정 유저에게만 보여줄 수 있나요?

A: 네, 발동 조건을 설정하여 특정 조건을 만족하는 유저에게만 표시할 수 있습니다.

Q: 보상이 중복 지급되지 않나요?

A: 기본적으로 유저당 1회만 참여 및 보상 지급이 가능합니다.

이전 장: ← 제 10장: 쿠폰 관리
다음 장: 제 12장: 배너 관리 →

제 12장: 상점 상품 관리 (Store Products)

게임 내 상점에서 판매되는 상품들을 관리합니다. 주로 기획 데이터 동기화를 통해 상품이 등록되며, 대시보드에서는 판매 상태와 세부 설정을 조정할 수 있습니다.

경로: 게임 관리 (Game) → 스토어 상품관리 (Store Products)
필요 권한: store-products.manage

1. 화면 구성

상점 상품 관리 페이지의 전체 화면입니다.

상점 상품 목록 화면

상단 툴바 버튼 설명

버튼 설명
상품 추가 새 상품 추가 (기획 데이터 동기화 권장)
배치 프로세스 여러 상품 일괄 처리

테이블 컬럼 설명

컬럼 설명
판매여부 현재 판매 중 여부
CMS ID 기획 데이터 시스템 ID
상품 ID 상품 고유 식별자
상품명 상품 표시 이름
스토어 판매 스토어 (IAP, 인게임 등)
가격 판매 가격
시작/종료 판매 기간
태그 분류용 태그
작업 ✏️ 편집, 🗑️ 삭제 버튼

2. 상품 등록 방법

방법 1: 기획 데이터 동기화 (권장)

상점 상품은 주로 기획 데이터(Excel/JSON)에서 정의되어 동기화됩니다.

flowchart LR
    A[Excel 기획서] --> B[데이터 빌드]
    B --> C[Gatrix 업로드]
    C --> D[상품 자동 등록]

    style D fill:#c8e6c9

방법 2: 직접 추가

대시보드에서 직접 상품을 추가할 수도 있습니다.

3. 상품 상태 관리

판매 상태

상태 설명
판매 중 유저가 구매 가능
판매 중지 목록에서 숨김
기간 한정 특정 기간에만 판매

판매 기간 설정

flowchart TD
    A[상품 등록] --> B{기간 설정?}
    B -->|설정함| C[시작~종료일 지정]
    B -->|설정 안함| D[상시 판매]
    C --> E[기간 내 자동 판매]

    style E fill:#c8e6c9

4. 스토어 종류

스토어 설명 결제 방식
IAP 인앱 결제 상품 실제 현금
인게임 게임 재화 상품 골드, 젬 등
이벤트 이벤트 한정 상품 재화/현금 혼합

5. 배치 프로세스

여러 상품을 한 번에 처리할 때 사용합니다.

작업 설명
일괄 판매 시작 선택한 상품들 판매 시작
일괄 판매 중지 선택한 상품들 판매 중지
일괄 삭제 선택한 상품들 삭제

6. 자주 묻는 질문 (FAQ)

Q: 상품 가격을 변경하면 기존 구매자에게 영향이 있나요?

A: 아니요, 가격 변경은 이후 구매에만 적용됩니다. 기존 구매는 영향받지 않습니다.

Q: 기획 데이터와 충돌하면 어떻게 되나요?

A: 기획 데이터 동기화 시 최신 데이터로 덮어씌워집니다. 대시보드에서 수정한 내용은 유지하려면 기획 측에 반영을 요청하세요.

이전 장: ← 제 11장: 설문조사 관리
다음 장: 제 13장: 배너 관리 →

제 12장: 배너 관리 (Banner Management)

게임 내 배너는 이벤트 홍보, 상품 광고, 신규 콘텐츠 안내 등에 활용됩니다. Gatrix에서는 시퀀스 기반의 동적 배너를 생성하고 관리할 수 있습니다.

경로: 게임 관리 (Game) → 배너 관리 (Banner Management)
필요 권한: banners.manage

1. 화면 구성

배너 관리 페이지의 전체 화면입니다.

배너 관리 목록 화면

상단 툴바 버튼 설명

버튼 설명
배너 추가 새로운 배너를 생성합니다.

테이블 컬럼 설명

컬럼 설명
이름 배너 이름 (관리용)
설명 배너에 대한 부가 설명
크기 배너 사이즈 (예: 1024×512)
시퀀스 배너에 포함된 프레임/시퀀스 수
상태 활성(Active) / 비활성(Inactive)
버전 배너 버전 (수정 시 버전 업)
생성일 배너 생성 일시
작업 ✏️ 편집, 🗑️ 삭제 버튼

2. 배너 생성하기

[배너 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.

배너 추가 폼

입력 항목 상세 설명

섹션 항목 필수 설명
기본 정보 이름 ✅ 배너 이름 (예: main_banner, event_2024)
설명 배너에 대한 부가 설명
크기 프리셋 ✅ 배너 사이즈 선택 (예: 1024×512)
재생 속도 시퀀스 전환 속도 (초 단위)
사용 배너 활성화 여부
시퀀스 시퀀스 목록 배너에 포함될 프레임들
미리보기 배너 미리보기 실시간으로 배너 렌더링 결과 확인

3. 시퀀스 기반 배너 구조

Gatrix 배너는 여러 시퀀스(프레임)로 구성됩니다.

flowchart LR
    A[시퀀스 1<br/>이벤트 A] --> B[시퀀스 2<br/>이벤트 B]
    B --> C[시퀀스 3<br/>신규 상품]
    C --> A

    style A fill:#e3f2fd
    style B fill:#c8e6c9
    style C fill:#fff9c4

시퀀스 설정 항목

항목 설명
이미지 URL 배너 프레임 이미지 경로
링크 URL 클릭 시 이동할 URL (선택)
노출 시간 해당 프레임 표시 시간
순서 프레임 표시 순서

4. 크기 프리셋

게임 내 배치 위치에 따라 적절한 크기를 선택합니다.

프리셋 크기 권장 용도
1024×512 (2:1) 가로형 메인 배너, 이벤트 배너
512×512 (1:1) 정사각형 아이콘, 썸네일
512×1024 (1:2) 세로형 사이드 배너, 팝업

배너 노출 로직

flowchart LR
    A[배너 1] -->|5초| B[배너 2]
    B -->|5초| C[배너 3]
    C -->|5초| A

5. 운영 시나리오

시나리오: 이벤트 배너 교체

flowchart TD
    A[신규 이벤트 기획] --> B[배너 이미지 제작]
    B --> C[시퀀스 추가]
    C --> D[미리보기 확인]
    D --> E{만족?}
    E -->|예| F[저장 및 배포]
    E -->|아니오| C

    style F fill:#c8e6c9
  1. [배너 추가] 또는 기존 배너 [편집] 클릭
  2. 새 이벤트 이미지 URL 입력
  3. 링크 URL 설정 (이벤트 상세 페이지)
  4. 미리보기에서 확인
  5. [저장]

6. 자주 묻는 질문 (FAQ)

Q: 배너 이미지는 어디에 업로드하나요?

A: 배너 이미지는 별도의 CDN이나 이미지 호스팅 서비스에 업로드한 후, URL을 입력합니다. Gatrix에서는 이미지 URL만 관리합니다.

Q: 시퀀스 순서를 변경하려면?

A: 시퀀스 목록에서 드래그 앤 드롭으로 순서를 변경할 수 있습니다.

이전 장: ← 제 11장: 상점 상품 관리
다음 장: 제 13장: 기획 데이터 관리 →

제 13장: 기획 데이터 관리 (Planning Data)

기획 데이터는 게임의 밸런스, 아이템 정보, 스테이지 설정 등 핵심 콘텐츠 데이터를 관리합니다. Excel로 작성된 기획 데이터를 JSON으로 변환하여 게임에 적용합니다.

경로: 게임 관리 (Game) → 기획데이터 → 기획데이터 관리
필요 권한: planning-data.manage

1. 화면 구성

데이터 처리 파이프라인

flowchart LR
    A[Excel 수정] --> B[Gatrix 업로드]
    B --> C[자동 검증]
    C -->|성공| D[JSON 변환 및 배포]
    C -->|실패| E[에러 리포트]

    style D fill:#c8e6c9
    style E fill:#ffcdd2

상단 툴바 버튼 설명

버튼 설명
새로고침 현재 데이터 목록 새로고침
기획데이터 업로드 새로운 기획 데이터 업로드

2. 업로드 방법 안내

기획 데이터를 업로드하는 방법은 크게 3가지입니다.

방법 1: 웹 UI를 통한 업로드

  1. [기획데이터 업로드] 버튼 클릭
  2. 파일 선택기에서 Excel/JSON 파일 선택
  3. 업로드 완료

방법 2: CMS → JSON 변환 (빌드)

CMS 폴더의 원본 데이터를 JSON 파일로 변환하는 과정입니다.

flowchart LR
    A[CMS 폴더<br/>원본 데이터] --> B[데이터 빌드<br/>yarn 명령]
    B --> C[JSON 파일<br/>언어별 생성]
    C --> D[Gatrix 업로드]

    style A fill:#e3f2fd
    style D fill:#c8e6c9

CLI 명령어:

# 프로젝트 루트에서 실행 (권장)
yarn planning-data:convert

# 옵션 사용
yarn planning-data:convert --input <CMS폴더경로> --output <출력폴더경로>

# 도움말 보기
yarn planning-data:convert --help

옵션 설명:

옵션 설명 기본값
--input <path> CMS 폴더 경로 ./packages/backend/cms
--output <path> 출력 폴더 경로 ./packages/backend/data/planning
--verbose 상세 로깅 -

방법 3: CLI를 통한 원격 업로드

빌드된 JSON 파일들을 원격 Gatrix 서버에 업로드합니다.

# 기본 사용법
yarn upload-planning-data \
  --api-url=https://gatrix.example.com \
  --env=production \
  --dir=./packages/backend/data/planning \
  --token=<SERVER_API_TOKEN>

# 업로더 이름 및 코멘트 추가 (CI/CD용)
yarn upload-planning-data \
  --api-url=https://gatrix.example.com \
  --env=qa \
  --dir=./planning-data \
  --token=$GATRIX_API_TOKEN \
  --uploader="Jenkins CI" \
  --comment="Build #123"

옵션 설명:

옵션 필수 설명
--api-url ✅ Gatrix 백엔드 API URL
--env ✅ 대상 환경 (dev, qa, production)
--dir ✅ 업로드할 JSON 파일이 있는 폴더
--token ✅ Server API 토큰 (환경변수 GATRIX_API_TOKEN으로도 설정 가능)
--uploader 업로더 이름 (예: "Jenkins CI")
--comment 업로드 코멘트

3. 데이터 동기화 플로우

flowchart TD
    subgraph 기획팀["📊 기획팀"]
        A[Excel 파일 작성] --> B[버전 관리<br/>Git/SVN]
    end

    subgraph 빌드["🔨 데이터 빌드"]
        B --> C[Excel → JSON 변환]
        C --> D[JSON 검증]
    end

    subgraph Gatrix["📡 Gatrix"]
        D --> E[기획데이터 업로드]
        E --> F[버전 생성]
        F --> G[환경별 배포]
    end

    subgraph 게임["🎮 게임 서버"]
        G --> H[Development]
        G --> I[Staging]
        G --> J[Production]
    end

    style A fill:#e3f2fd
    style J fill:#c8e6c9

4. 버전 관리

업로드된 기획 데이터는 버전으로 관리됩니다.

항목 설명
버전 업로드 시 자동 생성되는 버전 번호
업로드 일시 데이터 업로드 시간
업로더 업로드한 관리자
변경 내역 이전 버전과의 차이점
롤백 이전 버전으로 되돌리기

5. 히스토리 및 롤백

데이터 문제 발생 시 이전 버전으로 롤백할 수 있습니다.

flowchart TD
    A[문제 발생!<br/>v1.2.0 버그] --> B[히스토리 확인]
    B --> C[v1.1.0 선택]
    C --> D[롤백 실행]
    D --> E[이전 버전 적용]

    style A fill:#ffcdd2
    style E fill:#c8e6c9

6. 자주 묻는 질문 (FAQ)

Q: 기획 데이터 형식은 무엇인가요?

A: Excel(.xlsx) 또는 JSON 형식을 지원합니다. Excel 파일은 빌드 과정에서 JSON으로 자동 변환됩니다.

Q: 환경별로 다른 데이터를 적용할 수 있나요?

A: 네, 환경(Development, Staging, Production)별로 다른 버전의 데이터를 배포할 수 있습니다.

Q: 롤백하면 현재 데이터는 어떻게 되나요?

A: 롤백해도 현재 버전의 데이터는 히스토리에 남아있습니다. 언제든지 다시 적용할 수 있습니다.

이전 장: ← 제 12장: 배너 관리
다음 장: 제 14장: 리모트 컨피그 →

제 14장: 리모트 컨피그 (Remote Config)

리모트 컨피그는 앱 업데이트 없이 게임의 동작을 원격으로 제어할 수 있는 기능입니다. A/B 테스트, 기능 플래그, 동적 설정 변경 등에 활용됩니다.

경로: 관리자 패널 (Admin Panel) → 리모트 설정 (Remote Setting)
필요 권한: remote-config.manage

1. 화면 구성

리모트 컨피그 관리 페이지의 전체 화면입니다.

리모트 컨피그 화면

탭 구성

탭 설명
파라미터 기본 설정 값 관리
캠페인 A/B 테스트 캠페인 관리
컨텍스트 필드 유저 속성 필드 정의
세그먼트 유저 그룹 세분화
변형 실험 변형(Variant) 관리
배포 히스토리 배포 이력 확인

2. 파라미터 관리

게임에서 사용하는 설정 값들을 정의하고 관리합니다.

파라미터 목록 컬럼

컬럼 설명
파라미터 키 고유 식별자 (예: welcome_message)
타입 데이터 타입 (String, Number, Boolean, JSON)
기본값 기본 설정 값
설명 파라미터에 대한 설명
기능 적용된 기능 플래그
마지막 업데이트 최근 수정 일시

파라미터 타입

타입 용도 예시
String 공지 메시지, URL, 텍스트
Number 보너스 배율, 타이머 값
Boolean 기능 On/Off 플래그
JSON 복잡한 설정 객체

3. 리모트 컨피그 활용 플로우

flowchart TD
    subgraph Gatrix["🖥️ Gatrix 대시보드"]
        A[파라미터 정의] --> B[캠페인 생성<br/>A/B 테스트]
        B --> C[세그먼트 지정]
        C --> D[배포]
    end

    subgraph 게임["🎮 게임 클라이언트"]
        E[SDK 초기화] --> F[컨피그 요청]
        F --> G[설정 값 수신]
        G --> H[게임에 적용]
    end

    D --> F

    style D fill:#e3f2fd
    style H fill:#c8e6c9

4. A/B 테스트 (캠페인)

특정 유저 그룹에게 다른 설정 값을 적용하여 효과를 비교합니다.

flowchart LR
    A[전체 유저] --> B{세그먼트 분류}
    B -->|그룹 A<br/>50%| C[기존 UI]
    B -->|그룹 B<br/>50%| D[신규 UI]
    C --> E[지표 수집]
    D --> E
    E --> F[결과 분석]

    style C fill:#e3f2fd
    style D fill:#c8e6c9

캠페인 설정 항목

항목 설명
캠페인 이름 실험 식별용 이름
대상 파라미터 변경할 파라미터
변형 (Variant) 각 그룹별 설정 값
트래픽 배분 그룹별 유저 비율 (%)
기간 캠페인 진행 기간

5. 세그먼트 (유저 그룹)

특정 조건을 만족하는 유저 그룹을 정의합니다.

세그먼트 조건 예시

조건 설명 예시
플랫폼 OS 종류 iOS, Android
국가 접속 국가 KR, US, JP
앱 버전 클라이언트 버전 >= 2.0.0
유저 레벨 게임 내 레벨 >= 10
VIP 등급 결제 등급 Gold, Platinum

6. 운영 시나리오

시나리오: 신규 기능 점진적 롤아웃

flowchart LR
    A[새 기능 개발 완료] --> B[5% 유저 활성화]
    B --> C[모니터링 1주일]
    C --> D{문제 없음?}
    D -->|예| E[30% → 50% → 100%]
    D -->|아니오| F[0%로 비활성화]

    style E fill:#c8e6c9
    style F fill:#ffcdd2
  1. 파라미터 생성: new_feature_enabled (Boolean)
  2. 기본값: false
  3. 캠페인 생성: 5% 유저에게 true 적용
  4. 1주일 모니터링 후 점진적 확대

시나리오: 긴급 기능 비활성화

flowchart LR
    A[버그 발견] --> B[파라미터 값 변경<br/>true → false]
    B --> C[즉시 배포]
    C --> D[앱 업데이트 없이<br/>기능 비활성화]

    style A fill:#ffcdd2
    style D fill:#c8e6c9

7. 자주 묻는 질문 (FAQ)

Q: 파라미터 변경이 즉시 반영되나요?

A: 배포 후 클라이언트가 다음 요청 시 새 값을 받습니다. 즉시 반영이 필요하면 클라이언트에서 폴링 주기를 조정하세요.

Q: 배포를 롤백할 수 있나요?

A: 네, 배포 히스토리 탭에서 이전 버전으로 롤백할 수 있습니다.

이전 장: ← 제 13장: 기획 데이터 관리
다음 장: 제 15장: 감사 로그 →

제 15장: 감사 로그 (Audit Logs)

감사 로그는 대시보드에서 발생하는 모든 관리자 활동을 기록합니다. 보안 감사, 문제 추적, 책임 소재 확인에 필수적인 기능입니다.

경로: 관리자 패널 (Admin Panel) → 감사 로그 (Audit Log)
필요 권한: audit-logs.view

1. 화면 구성

감사 로그 페이지의 전체 화면입니다.

감사 로그 목록 화면

필터 옵션

필터 설명
오늘 오늘 발생한 로그만 표시
어제 어제 발생한 로그만 표시
7일 최근 7일 로그
1개월 최근 1개월 로그
사용자 지정 날짜 범위 직접 선택
사용자 검색 특정 사용자의 활동만 필터

테이블 컬럼 설명

컬럼 설명
생성일시 활동 발생 시간
사용자 활동을 수행한 관리자
작업 수행한 작업 종류
리소스 작업 대상 리소스 종류
리소스 ID 작업 대상의 고유 ID
IP 주소 접속 IP

2. 기록되는 활동 유형

주요 이벤트 목록

이벤트 설명 리소스
서비스 공지 고정 공지사항 상단 고정 서비스 공지
게임 월드 순서 변경 월드 목록 순서 수정 게임 월드
월드 편집 월드 정보 수정 게임 월드
사용자 생성 새 관리자 계정 생성 사용자
사용자 편집 관리자 정보/권한 수정 사용자
쿠폰 생성 새 쿠폰 발행 쿠폰
로그인 대시보드 로그인 사용자
감사 로그 조회 감사 로그 확인 감사 로그

3. 감사 로그 활용 시나리오

시나리오: "누가 이 공지를 수정했지?"

flowchart LR
    A[공지 오타 발견] --> B[감사 로그 접속]
    B --> C[리소스: 서비스 공지<br/>검색]
    C --> D[수정 내역 확인]
    D --> E[담당자 파악]

    style E fill:#c8e6c9
  1. 감사 로그 페이지 접속
  2. 리소스 검색: "서비스 공지"
  3. 해당 공지 ID로 필터링
  4. 최근 수정 이력 확인

시나리오: 보안 감사

flowchart TD
    A[보안 감사 요청] --> B[기간 설정<br/>지난 1개월]
    B --> C[모든 '사용자 생성'<br/>이벤트 필터]
    C --> D[비정상 패턴 확인]

    style D fill:#fff9c4

4. 상세 정보 확인

각 로그 항목을 클릭하면 상세 정보를 확인할 수 있습니다.

정보 설명
변경 전 데이터 수정 전 상태 (JSON)
변경 후 데이터 수정 후 상태 (JSON)
요청 정보 HTTP 메서드, 경로 등
사용자 에이전트 접속 브라우저/기기 정보

5. 자주 묻는 질문 (FAQ)

Q: 감사 로그는 얼마나 오래 보관되나요?

A: 기본적으로 90일간 보관됩니다. 보관 기간은 시스템 설정에서 조정할 수 있습니다.

Q: 감사 로그를 CSV로 내보낼 수 있나요?

A: 현재 버전에서는 화면에서 조회만 가능합니다. 내보내기가 필요하면 데이터베이스 담당자에게 문의하세요.

Q: 특정 사용자의 모든 활동을 추적하려면?

A: 검색창에 사용자 이메일을 입력하면 해당 사용자의 모든 활동 로그가 필터링됩니다.

이전 장: ← 제 14장: 리모트 컨피그
다음 장: 제 16장: API 토큰 관리 →

제 16장: API 토큰 관리 (API Access Tokens)

API 토큰은 외부 시스템(게임 서버, Edge 서버, CI/CD 파이프라인 등)이 Gatrix API에 접근할 때 인증에 사용됩니다.

경로: 관리자 패널 (Admin Panel) → 보안 (Security) → API 액세스 토큰
필요 권한: api-tokens.manage

🎬 영상 가이드: API 토큰 관리 방법 보기

1. 화면 구성

API 토큰 관리 페이지의 전체 화면입니다.

API 토큰 목록 화면

상단 툴바 버튼 설명

버튼 설명
토큰 생성 새로운 API 토큰을 생성합니다.

테이블 컬럼 설명

컬럼 설명
토큰 이름 토큰 식별용 이름
토큰 유형 API / Edge
환경 적용 환경 (dev, staging, production 등)
설명 토큰 용도 설명
사용 횟수 토큰이 사용된 횟수
마지막 사용일 최근 사용 일시
만료일 토큰 만료 예정일
생성일 토큰 생성 일시
작업 복사, ✏️ 편집, 🔄 재생성, 🗑️ 삭제 버튼

2. 토큰 유형

2.1 Server API 토큰

게임 서버가 Gatrix 백엔드 API를 호출할 때 사용합니다.

flowchart LR
    A[게임 서버] -->|Server Token| B[Gatrix Backend API]
    B --> C[데이터 조회/수정]

    style B fill:#e3f2fd

용도:
- 점검 상태 조회
- 공지사항 조회
- 쿠폰 검증
- 기획 데이터 동기화

2.2 Edge API 토큰

Edge 서버가 Gatrix Edge API를 호출할 때 사용합니다.

flowchart LR
    A[게임 클라이언트] --> B[Edge 서버]
    B -->|Edge Token| C[Gatrix Edge API]

    style C fill:#c8e6c9

3. 토큰 생성하기

[토큰 생성] 버튼을 클릭하여 새 토큰을 생성합니다.

입력 항목

항목 필수 설명
이름 ✅ 토큰 식별용 이름 (예: game-server-prod)
유형 ✅ API / Edge 선택
환경 ✅ 적용 환경 선택
설명 토큰 용도 메모
만료일 토큰 유효 기간 (비워두면 무기한)

4. 토큰 보안 관리

토큰 값 확인

토큰은 생성 시 한 번만 전체 값이 표시됩니다. 이후에는 마스킹된 형태로만 확인 가능합니다.

flowchart TD
    A[토큰 생성] --> B[전체 값 표시<br/>⚠️ 이때만 복사 가능!]
    B --> C[환경변수에 저장]
    C --> D[안전한 곳에 백업]

    style B fill:#fff9c4

⚠️ 중요: 토큰 값을 분실하면 재생성해야 합니다. 재생성하면 기존 토큰은 무효화됩니다.

토큰 재생성

보안상의 이유로 토큰을 변경해야 할 때 사용합니다.

  1. 목록에서 [🔄 재생성] 버튼 클릭
  2. 새 토큰 값이 생성됨
  3. 기존 토큰은 즉시 무효화됨
  4. 연결된 모든 서버의 토큰 업데이트 필요

5. 환경별 토큰 관리

보안을 위해 환경별로 별도의 토큰을 사용하는 것이 좋습니다.

환경 토큰 예시 보안 수준
Development dev-api-token 🟢 낮음
Staging staging-api-token 🟡 중간
Production prod-api-token 🔴 높음

💡 원칙: Production 토큰은 최소한의 인원만 접근 가능하도록 관리하세요.

6. 토큰 사용 예시

HTTP Header에 토큰 포함

curl -X GET https://api.gatrix.com/v1/game-worlds \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

환경변수 설정 (Node.js)

const GATRIX_API_TOKEN = process.env.GATRIX_API_TOKEN;

const response = await fetch('https://api.gatrix.com/v1/game-worlds', {
  headers: {
    'Authorization': `Bearer ${GATRIX_API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

7. 자주 묻는 질문 (FAQ)

Q: 토큰이 유출되었을 때 어떻게 하나요?

A: 즉시 해당 토큰의 [🔄 재생성] 버튼을 클릭하여 무효화하세요. 그리고 새 토큰을 서버에 적용하세요.

Q: 토큰에 만료일을 설정하는 것이 좋나요?

A: 보안 정책에 따라 다릅니다. 정기적인 토큰 교체가 필요하면 만료일을 설정하고, 만료 전에 재생성하세요.

Q: 사용 횟수가 비정상적으로 높으면?

A: 토큰 유출 또는 시스템 오류의 징후일 수 있습니다. 감사 로그를 확인하고 필요시 토큰을 재생성하세요.

8. 동영상 가이드

API 토큰 관리 전체 흐름

🎬
동영상 보기: 07-apitokens

클릭하여 새 창에서 재생하세요.

이전 장: ← 제 15장: 감사 로그

부록 A: 시스템 설정 가이드 (System Setup)

본 문서는 시스템 엔지니어 및 서버 관리자를 위한 설정 가이드입니다.
Gatrix의 이메일 발송 기능을 활성화하기 위한 SMTP 설정 방법을 안내합니다.

1. SMTP 이메일 설정

Gatrix는 사용자 초대, 비밀번호 재설정 등을 위해 SMTP 서버가 필요합니다.
서버 배포 시 아래 환경 변수(Environment Variables)를 설정해야 합니다.

필수 환경 변수

변수명 설명 예시
SMTP_HOST SMTP 서버 주소 smtp.gmail.com 또는 email-smtp.us-east-1.amazonaws.com
SMTP_PORT 포트 번호 587 (TLS) 또는 465 (SSL)
SMTP_USER SMTP 사용자 계정 admin@gatrix.com
SMTP_PASS SMTP 비밀번호 app-password-xxxx
SMTP_FROM 발신자 주소 "Gatrix Support" <noreply@gatrix.com>
SMTP_SECURE 보안 연결 사용 여부 true 또는 false

주요 서비스별 설정 예시

1) Gmail 사용 시 (테스트용)

Google 계정 설정에서 앱 비밀번호 (App Password)를 생성하여 사용해야 합니다.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=xxxx-xxxx-xxxx-xxxx
SMTP_SECURE=false

2) AWS SES (Amazon Simple Email Service)

프로덕션 환경에서 가장 권장되는 방식입니다.

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=AKIAxxxxxxxxxxxx
SMTP_PASS=Bxxxxxxxxxxxxxxxxxxxx
SMTP_SECURE=true

2. 문제 해결 (Troubleshooting)

이메일 발송 실패 시 점검 항목

  1. 방화벽 확인: 서버에서 SMTP 포트(587, 465, 25) 아웃바운드가 차단되어 있는지 확인하세요. (특히 AWS EC2의 경우 25번 포트는 기본 차단됩니다.)
  2. 인증 정보 확인: 아이디/비밀번호가 정확한지, 특수문자가 포함되어 있다면 이스케이프 처리가 필요한지 확인하세요.
  3. 발신자 주소 확인: 일부 SMTP 서버(AWS SES 등)는 사전에 인증된 발신자 도메인/이메일만 허용합니다.

📬 문의처

본 매뉴얼 또는 Gatrix 시스템에 대해 질문이 있으시면 Gatrix 개발팀에 문의해 주세요.

💡 Tip: 문의 시 환경(Environment), 오류 메시지, 재현 절차를 함께 알려주시면 더 빠른 지원이 가능합니다.